GIT-DCH(1) git-buildpackage Manual GIT-DCH(1)
NAME
git-dch - Generate the Debian changelog from git commit messages
SYNOPSIS
git-dch [ --verbose ] [ --debian-branch=branch_name ] [ --debian-tag=tag-format ] [ --upstream-tag=tag-format ] [ --ignore-branch ] [
--snapshot | --release ] [ --auto | --since=commitish ] [ --new-version=version ] [ --bpo | --nmu | --qa | --team ] [ --[no-]full ] [
--[no-]meta ] [ --meta-closes=bug-close-tags ] [ --snapshot-number=expression ] [ --id-length=number ] [ --git-log=git-log-options ] [
--[no-]git-author ] [ --[no-]multimaint ] [ --[no-]multimaint-merge ] [ --spawn-editor=[always|snapshot|release] ] [ --commit-msg=msg-for-
mat ] [ --commit ] [ --customization=customization-file ] [path1 path2]
DESCRIPTION
git-dch reads git commit messages and generates the Debian changelog from it. If no arguments are given git-dch starts from the last tagged
Debian package version up to the current tip of the current branch. If the distribution of the topmost section in debian/changelog is UNRE-
LEASED the changelog entries will be inserted into this section. Otherwise a new section will be created.
If --auto is given git-dch tries to guess the last Git commit documented in the changelog - this only works in snapshot mode. Otherwise
--since can be used to tell git-dch at which point it should start in the Git history.
The additional path arguments can be used to restrict the repository paths git-dch looks at. Setting path to debian/ is a good choice if
upstream uses Git and all Debian packaging changes are restricted to the debian/ subdir. In more sophisticated cases (like backports) you
can use --git-log to restrict the generated changelog entries further. E.g. by using --git-log="--author=Foo Bar".
OPTIONS
--debian-branch=branch_name
The branch in the Git repository the Debian package is being developed on, default is master.
--ignore-branch
Don't check if the current branch matches debian-branch.
--verbose
-v verbose execution
--debian-tag=tag-format
tag format used, when tagging debian versions, default is debian/%(version)s
--since=committish
Start reading commit messages at committish.
--auto, -a
Guess the last commit documented in the changelog from the snapshot banner (or from the last tag if no snapshot banner exists).
--[no-]meta
Parse meta tags like Closes:, Thanks: and Git-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.
--[no-]full
Include the full commit message in the changelog output.
--snapshot, -S
Create a snapshot release entry. This adds a snapshot release number and a warning banner to the changelog entry. The release ver-
sion number is being autoincremented with every new snapshot release to avoid packages downgrades during snapshot testing.
--snapshot-number=expression
Python expression that gets eval()ed to the new snapshot number.
--release, -R
Remove any snapshot release banners and version suffixes, set the current distribution to unstable and open the changelog for final
tweaking.
--new-version=version, -N version
Add a new changelog section with version newversion. Together with --snapshot the snapshot number will be appended to newversion.
--team Create a Team upload changelog entry.
--bpo Increment the Debian release number for an upload to backports, and add a backport upload changelog comment.
--nmu Increment the Debian release number for a non-maintainer upload.
--qa Increment the Debian release number for a Debian QA Team upload, and add a QA upload changelog comment.
--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]-multimaintmerge
Merge commits by maintainer.
--spawn-editor=[always|snapshot|release]
Whether to spawn an editor: always, 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.
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 git-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 subse-
quent invocations of git-dch -S so that later snapshots automatically have a higher version number. To leave snapshot mode invoke git-dch
with the --release option. This removes the pseudo heaader 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:
Git-Dch: action
Supported actions are: Ignore which will ignore this commit when generating debian/changelog, Short which will only use the descrip-
tion (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).
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 howto extend this for other bug-
trackers.
The following git commit message:
Document meta tags
so one doesn't have to consult the manual
Git-Dch: Short
Closes: #636088
Thanks: Raphael Hertzog for the suggestion
Results in this debian/changelog entry:
* Document meta tags.
Thanks to Raphael Hertzog for the suggestion (Closes: #636088)
CONFIGURATION FILES
Several gbp.conf files are parsed to set defaults for the above commandline arguments. See the [XRef to GBP.MAN.GBP.CONF] manpage for
details.
SEE ALSO
git-buildpackage(1), git-import-dsc(1), git-import-dscs(1), git-import-orig(1), gbp.conf(5), debuild(1), git(1), pristine-tar(1), The Git-
Buildpackage Manual <URL:file:///usr/share/doc/git-buildpackage/manual-html/index.html> Cl2vcs <URL:https://honk.sigxcpu.org/cl2vcs>,
AUTHOR
Guido Guenther <agx@sigxcpu.org>
01 June 2012 GIT-DCH(1)