&dhemail;
&dhfirstname;
&dhsurname;
gbp-dch
&dhsection;
gbp-dchGenerate the &debian; changelog from git commit messages
&gbp-dch;
&man.common.options.synopsis;
branch_nametag-formatbranch_nametag-formatcommitishcommitishversionversionnamelevellevelexpressionnumbergit-log-optionsmsg-formatcustomization-fileCOMMANDdch-optionspath1 path2DESCRIPTION
&gbp-dch; reads git commit messages and generates the &debian;
changelog from it. It starts at a given commit specified by the
option up to the current
HEAD. For each commit found it adds the
commit message to the changelog. If is
not given the commit to start from is determined by the
following rules (first one matches):
The start commit is read from the snapshot banner (see below for
details)If the topmost version of the
debian/changelog is alread tagged. Use the commit
the tag points to as start commit.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 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 option which is passed
on verbatim to git log. E.g. by using
"--author=Foo
Bar".
The above relies on the option
pointing to the current branch and
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 and
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.
OPTIONS
&man.common.options.description;
=branch_name
The branch in the Git repository the Debian package is being
developed on, default is master.
=branch_name
Branch to determine the upstream version from.
Default is upstream.
TAG-FORMAT
Use this tag format when looking for tags of upstream versions,
default is upstream/%(version)s.
Don't check if the current branch matches
debian-branch.
tag-format
Tag format used, when tagging debian versions,
default is debian/%(version)scommittish
Start reading commit messages at
committish.
This option can't be set via &gbp.conf;.
,
This option is ignored for compatibility with older
versions. It used to trigger automatic mode.
Parse meta tags like ,
and . See META TAGS
below.
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.
bug-number-format
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:
"(?: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.
,
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.
expression
Python expression that gets eval()ed to the new snapshot number.
,
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.
version,
version
Add a new changelog section with version
newversion. Together with
, the snapshot number will be appended to
newversion.
This option can't be set via &gbp.conf;.
Create a Team upload changelog entry.
This option can't be set via &gbp.conf;.
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;.
Increment the Debian release number for a non-maintainer upload.
This option can't be set via &gbp.conf;.
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;.
name
Set the distribution field to name.
This option can't be set via &gbp.conf;.
Force the distribution specified with
to be used, even if it doesn't match the list of known distributions.
This option can't be set via &gbp.conf;.
level
Set the urgency field to level.
git-log-options
Options passed on verbatim to git-log(1).
N
Include N digits of the commit id in the
changelog entry. Default is to not include any commit ids at all.
regex
Ignore commit lines matching regex
when generating the changelog.
Use user.name and user.email 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 release.
msg-format
Use this format string for the commit message when committing the
generated changelog file (when is given).
Default is
Update changelog for %(version)s release
Commit the generated changelog.
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.
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-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 or , &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; so that later snapshots automatically
have a higher version number. To leave snapshot mode, invoke &gbp-dch;
with the 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 option. The tags must start at the first column of
a commit message but can appear on any line.
They are of the form :
value. Valid Meta Tags are:
: 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 is given), and
Full which will use the full
commit message when generating the changelog entry (useful
when is not given).
In addition to , the
deprecated is still supported.
: msg
Add a thanks message after the commit message.
: bugnumber
Indicate in the debian/changelog that the bug
was closed by this commit. See the 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)
&man.gbp.config-files;
SEE ALSO,
,
,
,
,
&man.seealso.common;
Cl2vcs,
AUTHOR
&dhusername; &dhemail;