.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "GBP-DCH" "1" "29 October 2014" "" "git-buildpackage Manual"

.SH NAME
git-dch;, gbp-dch; \- Generate the Debian changelog from git commit messages
.SH SYNOPSIS

\fBgbp dch\fR [ \fB--version\fR ] [ \fB--help\fR ] [ \fB--verbose\fR ] [ \fB--color=\fI[auto|on|off]\fB\fR ] [ \fB--color-scheme=\fICOLOR_SCHEME\fB\fR ] [ \fB--debian-branch=\fIbranch_name\fB\fR ] [ \fB--debian-tag=\fItag-format\fB\fR ] [ \fB--upstream-tag=\fItag-format\fB\fR ] [ \fB--ignore-branch\fR ] [ \fB--snapshot\fR | \fB--release\fR ] [ \fB--auto\fR | \fB--since=\fIcommitish\fB\fR ] [ \fB--new-version=\fIversion\fB\fR ] [ \fB--bpo\fR | \fB--nmu\fR | \fB--qa\fR | \fB--team\fR ] [ \fB--distribution=\fIname\fB\fR ] [ \fB--force-distribution\fR ] [ \fB--urgency=\fIlevel\fB\fR ] [ \fB--[no-]full\fR ] [ \fB--[no-]meta\fR ] [ \fB--meta-closes=bug-close-tags\fR ] [ \fB--snapshot-number=\fIexpression\fB\fR ] [ \fB--id-length=\fInumber\fB\fR ] [ \fB--git-log=\fIgit-log-options\fB\fR ] [ \fB--[no-]git-author\fR ] [ \fB--[no-]multimaint\fR ] [ \fB--[no-]multimaint-merge\fR ] [ \fB--spawn-editor=[always|snapshot|release]\fR ] [ \fB--commit-msg=\fImsg-format\fB\fR ] [ \fB--commit\fR ] [ \fB--customizations=\fIcustomization-file\fB\fR ] \fB\fI[path1 path2]\fB\fR

.SH "DESCRIPTION"
.PP
\fBgbp dch\fR reads git commit messages and generates the Debian changelog from
it. If no arguments are given \fBgbp dch\fR 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
\fIdebian/changelog\fR is \fBUNRELEASED\fR
the changelog entries will be inserted into this section. Otherwise a new
section will be created.
.PP
If \fB--auto\fR is given \fBgbp dch\fR tries to guess the
last Git commit documented in the changelog - this only works in snapshot
mode. Otherwise \fB--since\fR can be used to tell \fBgbp dch\fR
at which point it should start in the Git history.
.PP
The additional path arguments can be used to restrict the repository paths
\fBgbp dch\fR looks at. Setting \fIpath\fR to
\fBdebian/\fR is a good choice if upstream uses Git and
all Debian packaging changes are restricted to the
\fIdebian/\fR subdir. In more sophisticated cases
(like backports) you can use \fB--git-log\fR to restrict the
generated changelog entries further. E.g. by using
\fB--git-log=\fR\fI"--author=Foo Bar"\fR\&.
.SH "OPTIONS"
.TP
\fB--version\fR
Print version of the program, i.e. version of the git-buildpackage
suite
.TP
\fB-v\fR
.TP
\fB--verbose\fR
Verbose execution
.TP
\fB-h\fR
.TP
\fB--help\fR
Print help and exit
.TP
\fB--color=\fI[auto|on|off]\fB \fR
Whether to use colored output.
.TP
\fB--color-scheme=\fICOLOR_SCHEME\fB \fR
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).
.TP
\fB--debian-branch=\fIbranch_name\fB \fR
The branch in the Git repository the Debian package is being
developed on, default is \fImaster\fR\&.
.TP
\fB--ignore-branch \fR
Don't check if the current branch matches
\fIdebian-branch\fR\&.
.TP
\fB--debian-tag=\fItag-format\fB \fR
tag format used, when tagging debian versions,
default is \fIdebian/%(version)s\fR
.TP
\fB--since=\fIcommittish\fB \fR
Start reading commit messages at
\fIcommittish\fR\&.
.TP
\fB--auto, -a\fR
Guess the last commit documented in the changelog from the
snapshot banner (or from the last tag if no snapshot banner exists).
.TP
\fB--[no-]meta\fR
Parse meta tags like \fBCloses:\fR,
\fBThanks:\fR and \fBGit-Dch:\fR\&. See META TAGS
below.
.TP
\fB--meta-closes=\fIbug-close-tags\fB \fR
What meta tags to look for to generate bug-closing changelog entries.
The default is 'Closes|LP' to support Debian and Launchpad.
.TP
\fB--[no-]full \fR
Include the full commit message in the changelog output.
.TP
\fB--snapshot, -S\fR
Create a snapshot release entry. This adds a snapshot release
number and a warning banner to the changelog entry. The release
version number is being auto incremented with every new snapshot
release to avoid packages downgrades during snapshot testing.
.TP
\fB--snapshot-number=\fIexpression\fB \fR
Python expression that gets eval()ed to the new snapshot number.
.TP
\fB--release, -R\fR
Remove any snapshot release banners and version suffixes, set
the current distribution to \fIunstable\fR and
open the changelog for final tweaking.
.TP
\fB--new-version=\fIversion\fB, -N \fIversion\fB \fR
Add a new changelog section with version
\fInewversion\fR\&. Together with
\fB--snapshot\fR the snapshot number will be appended to
\fInewversion\fR\&.
.TP
\fB--team \fR
Create a Team upload changelog entry.
.TP
\fB--bpo \fR
Increment the Debian release number for an upload to backports, and
add a backport upload changelog comment.
.TP
\fB--nmu \fR
Increment  the  Debian  release  number  for a non-maintainer upload.
.TP
\fB--qa \fR
Increment the Debian release number for a Debian QA Team upload, and
add a QA upload changelog comment.
.TP
\fB--distribution=\fIname\fB \fR
Set the distribution field to \fIname\fR\&.
.TP
\fB--force-distribution \fR
Force the distribution specified with \fB--distribution\fR
to be used, even if it doesn't match the list of known distributions.
.TP
\fB--urgency=\fIlevel\fB \fR
Set the urgency field to \fIlevel\fR\&.
.TP
\fB--git-log=\fIgit-log-options\fB \fR
Options passed on verbatim to git-log(1).
.TP
\fB--id-length=\fIN\fB \fR
Include \fIN\fR digits of the commit id in the
changelog entry. Default is to not include any commit ids at all.
.TP
\fB--ignore-regex=\fIregex\fB \fR
Ignore commit lines matching \fIregex\fR
when generating the changelog.
.TP
\fB--git-author \fR
Use user.name and user.email from
\fBgit-config\fR(1) for changelog trailer.
.TP
\fB--[no-]multimaint-merge \fR
Merge commits by maintainer.
.TP
\fB--spawn-editor=\fI[always|snapshot|release]\fB \fR
Whether to spawn an editor: always, when doing snapshots or when
doing a release.
.TP
\fB--commit-msg=\fImsg-format\fB \fR
use this format string for the commit message when committing the
generated changelog file (when \fB--commit\fR is given).
Default is
\fIUpdate changelog for %(version)s release\fR
.TP
\fB--commit \fR
Commit the generated changelog.
.TP
\fB--customizations=\fIcustomization-file\fB \fR
Load Python code from \fIcustomization-file\fR\&.
At the moment, the only useful thing the code can do is define a
custom format_changelog_entry() function.
.SH "SNAPSHOT MODE"
.PP
Snapshot mode can be used for quick test and install cycles without
having to worry about version numbers or changelog entries.
.PP
When using \fB--snapshot\fR or \fB-S\fR \fBgbp dch\fR
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
\fI~<snaspshotnumber>\&.gbp<commitid>\fR\&.
It automatically increments the snapshot number on subsequent invocations
of \fBgbp dch\fR \fB-S\fR so that later snapshots automatically
have a higher version number. To leave snapshot mode invoke \fBgbp dch\fR
with the \fB--release\fR option. This removes the pseudo
header and unmangles the version number so the released version has a
higher version number than the snapshots.
.SH "META TAGS"
.PP
Additional to the above options the formatting of the commit message
in \fIdebian/changelog\fR can be modified by special tags
(called Meta Tags)
given in the git commit message. Meta Tag processing can be activated via
the \fB--meta\fR option. The tags must start at the first column of
a commit message but can appear on any line.
They are of the form \fBTagname\fR:
\fIvalue\fR\&. Valid Meta Tags are:
.TP
\fBGit-Dch: \fIaction\fB \fR
Supported actions are: \fIIgnore\fR which will
ignore this commit when generating
\fIdebian/changelog\fR,
\fIShort\fR which will only use the description
(the first line) of the commit message when generating the changelog
entry (useful when \fB--full\fR is given) and
\fIFull\fR which will use the full commit
message when generating the changelog entry (useful when
\fB--full\fR is not given).
.TP
\fBThanks: \fImsg\fB \fR
Add a thanks message after the commit message.
.TP
\fBCloses: \fIbugnumber\fB \fR
Indicate in the \fIdebian/changelog\fR that the bug
was closed by this commit. See the \fB--meta-closes\fR on
how to extend this for other bugtrackers.
.PP
The following git commit message:

.nf
      Document meta tags

      so one doesn't have to consult the manual

      Git-Dch: Short
      Closes: #636088
      Thanks: Raphaël Hertzog for the suggestion
    
.fi
.PP
Results in this \fIdebian/changelog\fR entry:

.nf
      * Document meta tags.
        Thanks to Raphaël Hertzog for the suggestion (Closes: #636088)
    
.fi
.SH "CONFIGURATION FILES"
.PP
Several \fIgbp.conf\fR files are parsed 
to set defaults for the above commandline arguments. See the
\fBgbp.conf\fR(5) manpage for details.
.SH "SEE ALSO"
.PP
\fBgbp-buildpackage\fR(1),
\fBgbp-import-dsc\fR(1),
\fBgbp-import-dscs\fR(1),
\fBgbp-import-orig\fR(1),
\fBgbp.conf\fR(5),
\fBdebuild\fR(1),
\fBgit\fR(1),
\fBpristine-tar\fR(1),
\fIThe Git-Buildpackage Manual\fR <URL:file:///usr/share/doc/git-buildpackage/manual-html/index.html>
\fICl2vcs\fR <URL:https://honk.sigxcpu.org/cl2vcs>,
.SH "AUTHOR"
.PP
Guido Guenther <agx@sigxcpu.org>