dch

       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 tempo-
       rary file, debchange will exit without touching the existing changelog.
       Note  that the changelog is assumed to be encoded with the UTF-8 encod-
       ing.  If it is not, problems may occur.  Please see the  iconv(1)  man-
       page  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 deter-
       mine the title of the bug and the package in which it occurs.  This be-
       haviour  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 --newver-
       sion 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 spec-
       ified 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 configu-
       ration 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
       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/mail-
       name,  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 ver-
       sion'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.  Cur-
       rently  only  one of the several such styles of recording this informa-
       tion is supported, in which the name of the maintainer who made  a  set
       of  changes  appears on a line before the changes, inside square brack-
       ets. 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  behav-
              iour.

       2      Always check the directory name.

       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  num-
              ber  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  pres-
              ence 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 direc-
              tory name using the --fromdirname  option  or  entered  manually

       --package package
              This specifies the package name to be used in the new changelog;
              this may only be used in conjunction with the --create, --incre-
              ment 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  num-
              ber 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 num-
              ber.

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

       --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 num-
              ber 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 distri-
              bution 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 exist-
              ing 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  environ-
              ment  variable setting.  Also, no directory traversing or check-
              ing 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
              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  interest-
              ing  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,  DEBE-
              MAIL,  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 pack-
              age 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-main-
              tainer  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 explana-
              tion of this option.

       --check-dirname-regex regex
              See the above section "Directory name checking" for an  explana-
              tion 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
              put).  See --distributor for details.

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

       DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
              See  the above section "Directory name checking" for an explana-
              tion of these variables.  Note that these are package-wide  con-
              figuration  variables,  and will therefore affect all devscripts
              scripts which check their value, as described in  their  respec-
              tive 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 --nomaint-
              trailer 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 automat-
              ically 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
              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>.



DEBIAN                         Debian Utilities                   DEBCHANGE(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.