Provided by: git-buildpackage_0.9.29_all bug


       gbp-dch - Generate the Debian changelog from git commit messages


       gbp dch [--version] [--help] [--verbose] [--color=[auto|on|off]] [--color-scheme=
               COLOR_SCHEME] [--debian-branch= branch_name] [--debian-tag= tag-format]
               [--upstream-branch= branch_name] [--upstream-tag= tag-format] [--ignore-branch]
               [-s commitish | --since= commitish] [[-S | --snapshot] | [-R | --release]] [-N
               version | --new-version= version] [--bpo | --nmu | --qa | --security | --team |
               --local= suffix] [--distribution= name] [--force-distribution] [-U level |
               --urgency= level] [--[no-]full] [--[no-]meta] [--meta-closes=bug-close-tags]
               [--meta-closes-bugnum=bug-number-format] [--snapshot-number= expression] [--id-
               length= number] [--git-log= git-log-options] [--[no-]git-author]
               [--[no-]multimaint] [--[no-]multimaint-merge] [--spawn-
               editor=[always|never|snapshot|release]] [--commit-msg= msg-format] [-c | --commit]
               [--customizations= customization-file] [--postedit= COMMAND] [--dch-opt= dch-
               options]... [--verbose] path1 path2


       gbp dch reads git commit messages and generates the Debian changelog from it. It starts at
       a given commit specified by the --since option up to the current  HEAD.  For  each  commit
       found  it  adds the commit message to the changelog. If --since is not given the commit to
       start from is determined by the following rules (first one matches):

       1.  The start commit is read from the snapshot banner (see below for details)

       2.  If the topmost version of the debian/changelog is alread tagged. Use  the  commit  the
           tag points to as start commit.

       3.  The last commit that modified debian/changelog is used as start commit.

       This is called automatic mode.

       If  the  distribution  of  the  topmost  section  in  debian/changelog  is UNRELEASED, the
       changelog entries will be inserted into this section. Otherwise  a  new  section  will  be

       If  one  ore  more  paths  are  given  as  arguments  gbp dch will only include changes in
       debian/changelog that affect these paths. E.g. using debian/ is a good choice if  upstream
       uses Git and you don't want the upstream history to end up in debian/changelog.

       To  restrict  the selected changes even further you can use use the --git-log option which
       is passed on verbatim to git log. E.g. by using --git-log="--author=Foo Bar".

       The above relies on  the  --debian-branch  option  pointing  to  the  current  branch  and
       --upstream-branch pointing to the corresponding upstream branch in order to find the right
       merge points of these branches. Furthermore gbp dch must be able to identify git tags from
       upstream  and  Debian  version  numbers.  If  you're  not  using  the  defaults  check the
       --upstream-tag and --debian-tag options and make sure they match the tags created by  e.g.
       gbp import-orig (when using tarballs) or upstream's tagging pattern (when using upstream's
       git directly).

       If not changelog exists yet it is created and the version number is derived from the  last
       upstream tag if found.


              Print version of the program, i.e. version of the git-buildpackage suite

       -v, --verbose
              Verbose execution

       -h, --help
              Print help and exit

              Whether to use colored output.

              Colors  to  use  in  output (when color is enabled). The format for COLOR_SCHEME is
              '<debug>:<info>:<warning>:<error>'.  Numerical values and color names are accepted,
              empty  fields  imply the default color. For example, --git-color-scheme='cyan:34::'
              would show debug messages in cyan, info messages in  blue  and  other  messages  in
              default (i.e. warning and error messages in red).

              The  branch in the Git repository the Debian package is being developed on, default
              is master.

              Branch to determine the upstream version from.  Default is upstream.

              Use this tag format  when  looking  for  tags  of  upstream  versions,  default  is

              Don't check if the current branch matches debian-branch.

              Tag format used, when tagging debian versions, default is debian/%(version)s

              Start  reading  commit  messages  at  committish.   This  option  can't  be set via

       --auto, -a
              This option is ignored for compatibility with older versions. It  used  to  trigger
              automatic mode.

              Parse meta tags like Closes:, Thanks: and Gbp-Dch:. See META TAGS below.

              What  meta tags to look for to generate bug-closing changelog entries.  The default
              is 'Closes|LP' to support Debian and Launchpad.

              What regular expression should be used to parse out the bug number.  The default is
              '(?:bug|issue)?\#?\s?\d+'.  Note: the regex should suppress all portions of the bug
              number that are not wanted using "(?:)", see Python regex manual for details.

              Example: --meta-closes-bugnum="(?:bug)?\s*ex-\d+" would match all of the following:

                               Possible Txt  Match?    Result
                               ------------  ------    ------
                               bug EX-12345    Y       EX-12345
                               ex-01273        Y       ex-01273
                               bug ex-1ab      Y       ex-1
                               EX--12345       N

              Include the full commit message in the changelog output.

       --snapshot, -S
              Create a snapshot release entry. It uses a snapshot release number which is smaller
              than the final release number and adds a warning banner to the changelog entry. The
              version number is being auto incremented with every new snapshot release.

              The snapshot banner is also used by gbp dch to determine which entries are  already
              in the changelog. This prevents duplicated entries in debian/changelog when you did
              not commit the changelog yet.

              Python expression that gets eval()ed to the new snapshot number.

       --release, -R
              Remove any snapshot release banners and version suffixes (if any), set the  current
              distribution  to  unstable,  and open the changelog for final tweaking. This option
              can't be set via gbp.conf. It's usually  used  to  finalize  the  changelog  before
              making a release.

       --new-version=version, -N version
              Add  a new changelog section with version newversion. Together with --snapshot, the
              snapshot number will be appended to newversion.   This  option  can't  be  set  via

       --team Create a Team upload changelog entry.  This option can't be set via gbp.conf.

       --bpo  Increment  the Debian release number for an upload to backports, and add a backport
              upload changelog comment.  This option can't be set via gbp.conf.

       --nmu  Increment the Debian release number for a non-maintainer upload.  This option can't
              be set via gbp.conf.

       --qa   Increment  the  Debian  release  number  for  a Debian QA Team upload, and add a QA
              upload changelog comment.  This option can't be set via gbp.conf.

              Increment the Debian release number  for  a  Debian  Security  Team  non-maintainer
              upload,  and  add a "Security Team upload" changelog comment.  This option can't be
              set via gbp.conf.

       --local=suffix, -l suffix
              Increment the Debian release number for a local build using the  specified  suffix.
              This option can't be set via gbp.conf.

              Set the distribution field to name.  This option can't be set via gbp.conf.

              Force the distribution specified with --distribution to be used, even if it doesn't
              match the list of known distributions.  This option can't be set via gbp.conf.

              Set the urgency field to level.

              Options passed on verbatim to git-log(1).

              Include N digits of the commit id in the changelog entry. Default is to not include
              any commit ids at all.

              Ignore commit lines matching regex when generating the changelog.

              Use and from git-config(1) for changelog trailer.

              Merge commits by maintainer.

              Whether  to  spawn  an  editor: always, never, when doing snapshots or when doing a

              Use this format string  for  the  commit  message  when  committing  the  generated
              changelog  file  (when  --commit  is  given).   Default  is  Update  changelog  for
              %(version)s release

              Commit the generated changelog.

              Load Python code from customization-file.  At the moment, the only useful thing the
              code can do is define a custom format_changelog_entry() function.

              RunCOMMAND  after changes to the changelog file have been finalized, That is, after
              dch has been run and possible text editor has been exited, but, before changes  are
              (possibly) committed to git.

              Pass  option  to dch verbatim. Note that gbp dch invokes dch multiple times and the
              option is passed to all invocations so not all dch options make sense here. Options
              may also conflict with options picked by gbp dch.


       Snapshot  mode can be used for quick test and install cycles without having to worry about
       version numbers or changelog entries.

       When using --snapshot or -S, gbp dch uses a pseudo  header  in  the  Debian  changelog  to
       remember the last git commit it added a changelog entry for. It also sets a version number
       ending in ~<snaspshotnumber>.gbp<commitid>.   It  automatically  increments  the  snapshot
       number  on subsequent invocations of gbp dch -S so that later snapshots automatically have
       a higher version number. To leave snapshot mode, invoke gbp dch with the --release option.
       This  removes  the  pseudo header and unmangles the version number so the released version
       has a higher version number than the snapshots.


       Additional to the above options, the formatting of the commit message in  debian/changelog
       can  be  modified by special tags (called Meta Tags) given in the git commit message. Meta
       Tag processing can be activated via the --meta option. The tags must start  at  the  first
       column  of  a  commit  message  but can appear on any line.  They are of the form Tagname:
       value. Valid Meta Tags are:

       Gbp-Dch: action
              Supported actions are:  Ignore  which  will  ignore  this  commit  when  generating
              debian/changelog, Short which will only use the description (the first line) of the
              commit message when generating the changelog entry (useful when --full  is  given),
              and Full which will use the full commit message when generating the changelog entry
              (useful when --full is not given).

              In addition to Gbp-Dch, the deprecated Git-Dch is still supported.

       Thanks: msg
              Add a thanks message after the commit message.

       Closes: bugnumber
              Indicate in the debian/changelog that the bug was closed by this  commit.  See  the
              --meta-closes on how to extend this for other bugtrackers.

       The following git commit message:

             Document meta tags

             so one doesn't have to consult the manual

             Gbp-Dch: Short
             Closes: #636088
             Thanks: Raphaël Hertzog for the suggestion

       Results in this debian/changelog entry:

             * Document meta tags.
               Thanks to Raphaël Hertzog for the suggestion (Closes: #636088)


       Several  gbp.conf  files  are parsed to set defaults for the above command-line arguments.
       See the gbp.conf(5) manpage for details.


       gbp-buildpackage(1),    gbp-import-dsc(1),     gbp-import-dscs(1),     gbp-import-orig(1),
       gbp.conf(5), debuild(1), git(1), pristine-tar(1), The Git-Buildpackage Manual ⟨file:///
       usr/share/doc/git-buildpackage/manual-html/index.html⟩ Cl2vcs ⟨
       cl2vcs⟩ ,


       Guido Günther <>

                                        29 September 2022                              gbp-dch(1)