Man Linux: Main Page and Category List


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


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


       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  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

       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
       their  corresponding  command-line  options  --check-dirname-level  and

       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

       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.


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

       --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.

              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)

              Do not do so. Note that a dummy changelog entry made 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.

              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.

              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.

              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

       --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

       --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 lenny-
              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  a  version  number to be less than the current one if the
              new version matches the specified pattern.

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

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

              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

              Should we attempt  to  query  the  BTS  when  generating  closes

       --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.

        --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

       --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.

              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.

              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.

       --[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.

              Display version and copyright information and exit successfully.


       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:

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

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

              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).

              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

              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.

              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.

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

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

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

              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.

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


              See the above  description  of  the  use  of  these  environment

              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.

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


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


       The  original author was Christoph Lameter <>.  Many
       substantial  changes  and  improvements  were  made  by  Julian  Gilbey