Provided by: git-buildpackage_0.9.38_all 
NAME
gbp-dch - Generate the debian/changelog from Git commit history
SYNOPSIS
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 commit-ish | --since= commit-ish] [[-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
DESCRIPTION
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 already 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 created.
If one or 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 up‐
stream 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 up‐
stream's git directly).
If not changelog exists yet it is created and the version number is derived from the last upstream tag if
found.
OPTIONS
--version
Print version of the program, i.e. version of the git-buildpackage suite
-v, --verbose
Verbose execution
-h, --help
Print help and exit
--color=[auto|on|off]
Whether to use colored output.
--color-scheme=COLOR_SCHEME
Colors to use in output (when color is enabled). The format for COLOR_SCHEME is '<debug>:<in‐
fo>:<warning>:<error>'. Numerical values and color names are accepted, empty fields imply the de‐
fault 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).
--debian-branch=branch_name
The branch in the Git repository the Debian package is being developed on, default is master.
--upstream-branch=branch_name
Branch to determine the upstream version from. Default is upstream.
--git-upstream-tag=TAG-FORMAT
Use this tag format when looking for tags of upstream versions, default is upstream/%(version)s.
--ignore-branch
Don't check if the current branch matches debian-branch.
--debian-tag=tag-format
Tag format used, when tagging debian versions, default is debian/%(version)s
--since=commit-ish
Start reading commit messages at commit-ish. This option can't be set via gbp.conf.
--auto, -a
This option is ignored for compatibility with older versions. It used to trigger automatic mode.
--[no-]meta
Parse meta tags like Closes:, Thanks: and Gbp-Dch:. See META TAGS below.
--meta-closes=bug-close-tags
What meta tags to look for to generate bug-closing changelog entries. The default is 'Closes|LP'
to support Debian and Launchpad.
--meta-closes-bugnum=bug-number-format
What regular expression should be used to parse out the bug number. The default is '(?:bug|is‐
sue)?\#?\s?\d+'. Note: the regex should suppress all portions of the bug number that are not want‐
ed 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
--[no-]full
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 changel‐
og. This prevents duplicated entries in debian/changelog when you did not commit the changelog
yet.
--snapshot-number=expression
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 gbp.conf.
--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 changel‐
og 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.
--security
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.
--distribution=name
Set the distribution field to name. This option can't be set via gbp.conf.
--force-distribution
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.
--urgency=level
Set the urgency field to level.
--git-log=git-log-options
Options passed on verbatim to git-log(1).
--id-length=N
Include N digits of the commit id in the changelog entry. Default is to not include any commit ids
at all.
--ignore-regex=regex
Ignore commit lines matching regex when generating the changelog.
--git-author
Use user.name and user.email from git-config(1) for changelog trailer.
--[no-]multimaint-merge
This option is passed verbatim to dch(1) and is enabled by default.
--spawn-editor=[always|never|snapshot|release]
Whether to spawn an editor: always, never, when doing snapshots or when doing a release.
--commit-msg=msg-format
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
Commit the generated changelog.
--customizations=customization-file
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.
--postedit=COMMAND
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.
--dch-opt=dch-option
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
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 ~<snaspshotnum‐
ber>.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.
META TAGS
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)
EXAMPLES
Update the latest debian/changelog so package is ready for release, and commit the change. A editor will
be spawned so the entry can be reviewed and manually refined easily.
gbp dch --release --commit
Right after running git import-orig --uscan, create a new debian/changelog entry for UNRELEASED, and in‐
clude only commits that modified something in the debian/ subdirectory so all upstream commits are ig‐
nored:
gbp dch --distribution=UNRELEASED \
--commit --commit-msg="Update changelog after new upstream version import" \
-- debian
CONFIGURATION FILES
Several gbp.conf files are parsed to set defaults for the above command-line arguments. See the
gbp.conf(5) manpage for details.
SEE ALSO
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 ⟨https://honk.sigxcpu.org/cl2vcs⟩ ,
AUTHOR
Guido Günther <agx@sigxcpu.org>
10 April 2025 gbp-dch(1)