Provided by: devscripts_2.11.6ubuntu1_amd64 bug

NAME

       debchange - Tool for maintenance of the debian/changelog file in a source package

SYNOPSIS

       debchange [options] [text ...]
       dch [options] [text ...]

DESCRIPTION

       debchange  or  its  alias  dch  will add a new comment line to the Debian changelog in the
       current source tree.  This command must be run from within that tree.  If the text of  the
       change  is  given on the command line, debchange will run in batch mode and simply add the
       text, with line breaks as necessary, at the appropriate place in debian/changelog (or  the
       changelog  specified  by  options,  as  described  below).   If  no text is specified then
       debchange will run the editor as determined by sensible-editor for you to edit  the  file.
       (The  environment  variables  VISUAL  and EDITOR are used in this order to determine which
       editor to use.)  Editors which understand the +n option for  starting  the  editing  on  a
       specified  line will use this to move to the correct line of the file for editing.  If the
       editor is quit without modifying the temporary file, debchange will exit without  touching
       the  existing  changelog.  Note that the changelog is assumed to be encoded with the UTF-8
       encoding.  If it is not, problems may occur.  Please see the iconv(1) manpage to find  out
       how to convert changelogs from legacy encodings.  Finally, a changelog or NEWS file can be
       created from scratch using the --create option described below.

       debchange also supports automatically producing bug-closing changelog entries,  using  the
       --closes  option.   This  will  usually query the BTS, the Debian Bug Tracking System (see
       http://bugs.debian.org/) to determine the title of the bug and the  package  in  which  it
       occurs.   This  behaviour  can  be  stopped by giving a --noquery option or by setting the
       configuration variable DEBCHANGE_QUERY_BTS to no, as described below.  In either case, the
       editor  (as  described  above) will always be invoked to give an opportunity to modify the
       entries, and the changelog will be accepted whether or not  modifications  are  made.   An
       extra changelog entry can be given on the command line in addition to the closes entries.

       At most one of --append, --increment, --edit, --release, and --newversion may be specified
       as listed below. If no options are specified,  debchange  will  use  heuristics  to  guess
       whether  or  not  the package has been successfully released, and behave as if --increment
       had been specified if the package has been released, or otherwise as if --append has  been
       specified.

       Two  different  sets  of  heuristics can be used, as controlled by the --release-heuristic
       option  or  the  DEBCHANGE_RELEASE_HEURISTIC  configuration  variable.  The  default   log
       heuristic  determines  if  a  package  has  been  released  by  looking for an appropriate
       dupload(1) or dput(1) log file in the parent directory. A warning will be  issued  if  the
       log  file  is  found  but  a  successful  upload  is not recorded. This may be because the
       previous upload was performed with a version of dupload prior to 2.1 or because the upload
       failed. The alternate changelog heuristic assumes the package has been released unless its
       changelog contains UNRELEASED in the distribution field. If this heuristic is enabled then
       the   distribution   will  default  to  UNRELEASED  in  new  changelog  entries,  and  the
       --mainttrailer option described below will be automatically enabled. This can be useful if
       a package can be released by different maintainers, or if you do not keep the upload logs.

       If either --increment or --newversion is used, the name and email for the new version will
       be determined as follows.  If the environment variable DEBFULLNAME is set,  this  will  be
       used  for the maintainer full name; if not, then NAME will be checked.  If the environment
       variable DEBEMAIL is set, this will be used for the email address.  If this  variable  has
       the  form "name <email>", then the maintainer name will also be taken from here if neither
       DEBFULLNAME nor NAME is set.  If this variable is not set, the same test is  performed  on
       the  environment  variable  EMAIL.   Next, if the full name has still not been determined,
       then use getpwuid(3) to determine the name from the password file.  If this fails, use the
       previous  changelog entry.  For the email address, if it has not been set from DEBEMAIL or
       EMAIL, then look in /etc/mailname, then attempt to build it from the  username  and  FQDN,
       otherwise  use  the email address in the previous changelog entry.  In other words, it's a
       good idea to set DEBEMAIL and DEBFULLNAME when using this script.

       Support is included for changelogs that record changes by  multiple  co-maintainers  of  a
       package.  If  an entry is appended to the current version's entries, and the maintainer is
       different from the maintainer who is listed as having  done  the  previous  entries,  then
       lines  will  be  added  to  the  changelog  to  tell which maintainers made which changes.
       Currently only one of the several such styles of recording this information is  supported,
       in which the name of the maintainer who made a set of changes appears on a line before the
       changes,  inside  square  brackets.  This  can  be  switched  on   and   off   using   the
       --[no]multimaint option or the DEBCHANGE_MULTIMAINT configuration file option; the default
       is to enable it.  Note that if an entry has already been marked in  this  way,  then  this
       option will be silently ignored.

       If the directory name of the source tree has the form package-version, then debchange will
       also attempt to rename it if the (upstream) version number changes.  This can be prevented
       by using the --preserve command line or configuration file option as described below.

       If  --force-bad-version  or  --allow-lower-version is used, debchange will not stop if the
       new version is less  than  the  current  one.   This  is  especially  useful  while  doing
       backports.

Directory name checking

       In  common  with several other scripts in the devscripts package, debchange will climb the
       directory tree until it finds a debian/changelog file.  As a safeguard against stray files
       causing potential problems, it will examine the name of the parent directory once it finds
       the debian/changelog file, and check that the directory name corresponds  to  the  package
       name.   Precisely  how  it  does  this  is  controlled by two configuration file variables
       DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding
       command-line options --check-dirname-level and --check-dirname-regex.

       DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:

       0      Never check the directory name.

       1      Only  check the directory name if we have had to change directory in our search for
              debian/changelog.  This is the default behaviour.

       2      Always check the directory name.

       The directory name is checked by testing whether the current directory name (as determined
       by    pwd(1))    matches    the   regex   given   by   the   configuration   file   option
       DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command line option --check-dirname-regex  regex.
       Here  regex  is  a Perl regex (see perlre(3perl)), which will be anchored at the beginning
       and the end.  If regex contains a '/', then it must match the  full  directory  path.   If
       not,  then it must match the full directory name.  If regex contains the string ´PACKAGE',
       this will be replaced by the source package name, as determined from the  changelog.   The
       default  value  for  the  regex is: ´PACKAGE(-.+)?', thus matching directory names such as
       PACKAGE and PACKAGE-version.

       The default changelog to be edited is debian/changelog; however, this can be changed using
       the  --changelog  or  --news  options  or the CHANGELOG environment variable, as described
       below.

OPTIONS

       --append, -a
              Add a new changelog entry at the end of the current version's entries.

       --increment, -i
              Increment either the final component of the Debian release number or, if this is  a
              native  Debian  package,  the  version  number.   This creates a new section at the
              beginning of the changelog with appropriate headers and footers.  Also, if this  is
              a  new version of a native Debian package, the directory name is changed to reflect
              this.

       --newversion version, -v version
              This specifies the version number (including the Debian  release  part)  explicitly
              and  behaves  as the --increment option in other respects.  It will also change the
              directory name if the upstream version number has changed.

       --edit, -e
              Edit the changelog in an editor.

       --release, -r
              Finalize the changelog for a release.   Update  the  changelog  timestamp.  If  the
              distribution  is set to UNRELEASED, change it to the distribution from the previous
              changelog entry (or another distribution as specified by --distribution).  If there
              are  no  previous  changelog  entries  and  an  explicit  distribution has not been
              specified, unstable will be used.

       --force-save-on-release
              When --release is used and an editor opened to allow inspection of  the  changelog,
              require  the  user  to  save  the  changelog  their  editor opened.  Otherwise, the
              original changelog will not be modified. (default)

       --no-force-save-on-release
              Do not do so. Note that a dummy changelog entry may be supplied in order to achieve
              the  same effect - e.g. debchange --release "".  The entry will not be added to the
              changelog but its presence will suppress the editor.

       --create
              This will create a new debian/changelog file (or  NEWS  if  the  --news  option  is
              used).   You  must  be  in  the  top-level directory to use this; no directory name
              checking will be performed.  The package name and version can either  be  specified
              using  the  --package  and --newversion options, determined from the directory name
              using the --fromdirname option or entered manually  into  the  generated  changelog
              file.   The maintainer name is determined from the environment if this is possible,
              and the distribution is specified either using the --distribution option or in  the
              generated changelog file.

       --empty
              When  used  in  combination  with  --create,  suppress the automatic addition of an
              "initial release" changelog entry (so that the next invocation  of  debchange  adds
              the  first  entry).  Note that this will cause a dpkg-parsechangelog warning on the
              next invocation due to the lack of changes.

       --package package
              This specifies the package name to be used in the new changelog; this may  only  be
              used in conjunction with the --create, --increment and --newversion options.

       --nmu, -n
              Increment the Debian release number for a non-maintainer upload by either appending
              a ".1" to a non-NMU version number (unless the package is Debian native,  in  which
              case  "+nmu1" is appended) or by incrementing an NMU version number, and add an NMU
              changelog comment.  This happens automatically if the packager is  neither  in  the
              Maintainer  nor the Uploaders field in debian/control, unless DEBCHANGE_AUTO_NMU is
              set to no or the --no-auto-nmu option is used.

       --bin-nmu
              Increment the Debian release number for a binary non-maintainer  upload  by  either
              appending  a  "+b1"  to  a  non-binNMU  version  number or by incrementing a binNMU
              version number, and add a binNMU changelog comment.

       --rebuild, -R
              Increment the Debian release number for a no-change rebuild by appending a "build1"
              or by incrementing a rebuild version number.

       --qa, -q
              Increment  the  Debian  release  number  for  a Debian QA Team upload, and add a QA
              upload changelog comment.

       --security, -s
              Increment the Debian release number  for  a  Debian  Security  Team  non-maintainer
              upload, and add a Security Team upload changelog comment.

       --team Increment  the  Debian  release  number  for  a  team upload, and add a Team upload
              changelog comment.

       --bpo  Increment the Debian release number for an upload to squeeze-backports, and  add  a
              backport upload changelog comment.

       --local, -lsuffix
               Add a suffix to the Debian version number for a local build.

       --force-bad-version, -b
              Force a version number to be less than the current one (e.g., when backporting).

       --allow-lower-version pattern
              Allow  a  version number to be less than the current one if the new version matches
              the specified pattern.

       --force-distribution
              Force the provided distribution to be used, even if it doesn't match  the  list  of
              known distributions (e.g. for unofficial distributions).

       --auto-nmu
              Attempt  to  automatically determine whether a change to the changelog represents a
              Non Maintainer Upload.  This is the default.

       --no-auto-nmu
              Disable automatic NMU detection.  Equivalent to setting DEBCHANGE_AUTO_NMU to no.

       --fromdirname, -d
              This will take the upstream version number from the directory name, which should be
              of the form package-version.  If the upstream version number has increased from the
              most recent changelog entry, then a new entry will  be  made  with  version  number
              version-1  (or version if the package is Debian native), with the same epoch as the
              previous package version.  If the upstream version number is the same, this  option
              will behave in the same way as -i.

       --closes nnnnn[,nnnnn ...]
              Add  changelog  entries to close the specified bug numbers.  Also invoke the editor
              after adding these entries.  Will generate warnings if the BTS cannot be  contacted
              (and  --noquery  has  not  been  specified),  or if there are problems with the bug
              report located.

       --[no]query
              Should we attempt to query the BTS when generating closes entries?

       --preserve, -p
              Preserve the source tree directory name if the  upstream  version  number  (or  the
              version  number  of  a  Debian native package) changes.  See also the configuration
              variables section below.

       --distributor vendor
              Override the distributor ID over the default returned by dpkg-vendor.  This name is
              used  for heuristics applied to new package versions and for sanity checking of the
              target distribution.

        --no-preserve, --nopreserve
              Do not preserve the source tree directory name (default).

       --distribution dist, -D dist
              Use the specified distribution in the changelog  entry  being  edited,  instead  of
              using  the  previous changelog entry's distribution for new entries or the existing
              value for existing entries.

       --urgency urgency, -u urgency
              Use the specified urgency in the changelog entry being edited, instead of using the
              default "low" for new entries or the existing value for existing entries.

       --changelog file, -c file
              This  will  edit the changelog file instead of the standard debian/changelog.  This
              option overrides any CHANGELOG environment variable setting.   Also,  no  directory
              traversing or checking will be performed when this option is used.

       --news [newsfile]
              This will edit newsfile (by default, debian/NEWS) instead of the regular changelog.
              Directory searching will be performed.  The changelog will be examined in order  to
              determine the current package version.

       --[no]multimaint
              Should  we  indicate  that  parts  of a changelog entry have been made by different
              maintainers?   Default  is  yes;  see   the   discussion   above   and   also   the
              DEBCHANGE_MULTIMAINT configuration file option below.

       --[no]multimaint-merge
              Should  all  changes  made  by  the  same  author be merged into the same changelog
              section?    Default   is   no;   see   the   discussion   above   and   also    the
              DEBCHANGE_MULTIMAINT_MERGE configuration file option below.

       --maintmaint, -m
              Do  not  modify the maintainer details previously listed in the changelog.  This is
              useful particularly for sponsors wanting to automatically add a sponsorship message
              without  disrupting  the  other  changelog  details.   Note  that there may be some
              interesting interactions if multi-maintainer mode is in use; you will probably wish
              to check the changelog manually before uploading it in such cases.

       --controlmaint, -M
              Use  maintainer  details  from  the  debian/control  Maintainer  field  rather than
              relevant environment variables (DEBFULLNAME, DEBEMAIL, etc.).  This option might be
              useful  to  restore details of the main maintainer in the changelog trailer after a
              bogus edit (e.g. when -m was intended but forgot) or when releasing  a  package  in
              the name of the main maintainer (e.g. the team).

       --[no]mainttrailer, -t
              If mainttrailer is set, it will avoid modifying the existing changelog trailer line
              (i.e. the maintainer and date-stamp details), unless used with options that require
              the  trailer to be modified (e.g. --create, --release, -i, --qa, etc.)  This option
              differs from --maintmaint in that it will use multi-maintainer mode if appropriate,
              with  the  exception  of  editing  the trailer. See also the DEBCHANGE_MAINTTRAILER
              configuration file option below.

       --check-dirname-level N
              See the above section "Directory name checking" for an explanation of this option.

       --check-dirname-regex regex
              See the above section "Directory name checking" for an explanation of this option.

       --no-conf, --noconf
              Do not read any configuration files.  This can only be used  as  the  first  option
              given on the command-line.

       --release-heuristic log|changelog
              Controls  how  debchange  determines  if a package has been released, when deciding
              whether to create a new changelog entry or append to an existing changelog entry.

       --help, -h
              Display a help message and exit successfully.

       --version
              Display version and copyright information and exit successfully.

CONFIGURATION VARIABLES

       The two configuration files /etc/devscripts.conf and ~/.devscripts  are  sourced  in  that
       order  to  set  configuration  variables.   Command  line  options can be used to override
       configuration file settings.  Environment variable settings are ignored for this  purpose.
       The currently recognised variables are:

       DEBCHANGE_PRESERVE
              If this is set to yes, then it is the same as the --preserve command line parameter
              being used.

       DEBCHANGE_DISTRIBUTOR
              Use  this  distributor  instead  of  the   default   (dpkg-vendor   output).    See
              --distributor for details.

       DEBCHANGE_QUERY_BTS
              If  this  is set to no, then it is the same as the --noquery command line parameter
              being used.

       DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
              See the above section  "Directory  name  checking"  for  an  explanation  of  these
              variables.   Note  that  these  are  package-wide configuration variables, and will
              therefore affect all devscripts scripts which check their value,  as  described  in
              their respective manpages and in devscripts.conf(5).

       DEBCHANGE_RELEASE_HEURISTIC
              Controls  how  debchange  determines  if a package has been released, when deciding
              whether to create a new changelog entry or append to an existing  changelog  entry.
              Can be either log or changelog.

       DEBCHANGE_MULTIMAINT
              If  set to no, debchange will not introduce multiple-maintainer distinctions when a
              different maintainer appends an entry to an existing changelog.  See the discussion
              above.  Default is yes.

       DEBCHANGE_MULTIMAINT_MERGE
              If set to yes, when adding changes in multiple-maintainer mode debchange will check
              whether previous changes by the current maintainer exist and add the new changes to
              the existing block rather than creating a new block.  Default is no.

       DEBCHANGE_MAINTTRAILER
              If  this  is  set  to  no, then it is the same as the --nomainttrailer command line
              parameter being used.

       DEBCHANGE_TZ
              Use this timezone for changelog entries.  Default is the  user/system  timezone  as
              shown by `date -R` and affected by the environment variable TZ.

       DEBCHANGE_LOWER_VERSION_PATTERN
              If  this  is  set,  then  it  is the same as the --allow-lower-version command line
              parameter being used.

       DEBCHANGE_AUTO_NMU
              If this is set to no then debchange will not  attempt  to  automatically  determine
              whether  the  current changelog stanza represents an NMU.  The default is yes.  See
              the discussion of the --nmu option above.

       DEBCHANGE_FORCE_SAVE_ON_RELEASE
              If this is set to no, then it is the same as the --no-force-save-on-release command
              line parameter being used.

ENVIRONMENT

       DEBEMAIL, EMAIL, DEBFULLNAME, NAME
              See the above description of the use of these environment variables.

       CHANGELOG
              This  variable  specifies  the  changelog to edit in place of debian/changelog.  No
              directory traversal or checking is performed  when  this  variable  is  set.   This
              variable is overridden by the --changelog command-line setting.

       VISUAL, EDITOR
              These  environment variables (in this order) determine the editor used by sensible-
              editor.

SEE ALSO

       debclean(1), dupload(1), dput(1), debc(1) and devscripts.conf(5).

AUTHOR

       The original author was Christoph Lameter <clameter@debian.org>.  Many substantial changes
       and improvements were made by Julian Gilbey <jdg@debian.org>.