.\" 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" "07 February 2017" "" "git-buildpackage Manual"

.SH NAME
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-branch=\fIbranch_name\fB\fR ] [ \fB--upstream-tag=\fItag-format\fB\fR ] [ \fB--ignore-branch\fR ] [ [ \fB-S\fR | \fB--snapshot\fR ] [ \fB-R\fR | \fB--release\fR ] ] [ [ \fB-a\fR | \fB--auto\fR ] [ \fB-s \fIcommitish\fB\fR | \fB--since=\fIcommitish\fB\fR ] ] [ \fB-N \fIversion\fB\fR | \fB--new-version=\fIversion\fB\fR ] [ \fB--bpo\fR | \fB--nmu\fR | \fB--qa\fR | \fB--security\fR | \fB--team\fR ] [ \fB--distribution=\fIname\fB\fR ] [ \fB--force-distribution\fR ] [ \fB-U \fIlevel\fB\fR | \fB--urgency=\fIlevel\fB\fR ] [ \fB--[no-]full\fR ] [ \fB--[no-]meta\fR ] [ \fB--meta-closes=bug-close-tags\fR ] [ \fB--meta-closes-bugnum=bug-number-format\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|never|snapshot|release]\fR ] [ \fB--commit-msg=\fImsg-format\fB\fR ] [ \fB-c\fR | \fB--commit\fR ] [ \fB--customizations=\fIcustomization-file\fB\fR ] [ \fB--verbose\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 commit corresponding to 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\&.
.PP
The above relies on the \fBdebian-branch\fR option
pointing to the current branch
and \fBupstream-branch\fR pointing to the
corresponding upstream branch in order to find the right merge
points of these branches. Furthermore \fBgbp\~dch\fR must be able to
identify git tags from upstream and Debian version numbers. If
you're not using the defaults check
the \fBupstream-tag\fR
and \fBdebian-tag\fR options.
.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,
\fB--git-color-scheme=\fR\&'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--upstream-branch=\fIbranch_name\fB \fR
Branch to determine the upstream version from.
Default is \fIupstream\fR\&.
.TP
\fB--git-upstream-tag=\fITAG-FORMAT\fB \fR
use this tag format when looking for tags of upstream versions,
default is \fIupstream/%(version)s\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\&.
This option can't be set via \fIgbp.conf\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).
This option can't be set via \fIgbp.conf\fR\&.
.TP
\fB--[no-]meta\fR
Parse meta tags like \fBCloses:\fR,
\fBThanks:\fR and \fBGbp-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--meta-closes-bugnum=\fIbug-number-format\fB \fR
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:
\fB--meta-closes-bugnum=\fR"(?:bug)?\\s*ex-\\d+"
would match all of the following:

.nf
                 Possible Txt  Match?    Result
                 ------------  ------    ------
                 bug EX-12345    Y       EX-12345
                 ex-01273        Y       ex-01273
                 bug ex-1ab      Y       ex-1
                 EX--12345       N
.fi
.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.
This option can't be set via \fIgbp.conf\fR\&.
.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\&.
This option can't be set via \fIgbp.conf\fR\&.
.TP
\fB--team \fR
Create a Team upload changelog entry.
This option can't be set via \fIgbp.conf\fR\&.
.TP
\fB--bpo \fR
Increment the Debian release number for an upload to backports, and
add a backport upload changelog comment.
This option can't be set via \fIgbp.conf\fR\&.
.TP
\fB--nmu \fR
Increment  the  Debian  release  number  for a non-maintainer upload.
This option can't be set via \fIgbp.conf\fR\&.
.TP
\fB--qa \fR
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 \fIgbp.conf\fR\&.
.TP
\fB--security \fR
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 \fIgbp.conf\fR\&.
.TP
\fB--distribution=\fIname\fB \fR
Set the distribution field to \fIname\fR\&.
This option can't be set via \fIgbp.conf\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.
This option can't be set via \fIgbp.conf\fR\&.
.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|never|snapshot|release]\fB \fR
Whether to spawn an editor: always, never, 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
\fB   Gbp-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).

In addition to \fBGbp-Dch\fR, the
deprecated \fBGit-Dch\fR is still supported.
.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

      Gbp-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 command-line 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>