Ubuntu Manpage: git-dch;, gbp-dch; - Generate the Debian changelog from git commit messages

NAME

       git-dch;, gbp-dch; - Generate the Debian changelog from git commit messages

SYNOPSIS

       gbp  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 ] [
       --distribution=name ] [ --force-distribution ] [  --urgency=level  ]  [  --[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-format ] [ --commit ] [ --customization=customization-file ] [path1 path2]

DESCRIPTION

       gbp dch reads git commit messages and generates  the  Debian  changelog  from  it.  If  no
       arguments  are  given gbp 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  UNRELEASED the changelog entries will be inserted into this section.
       Otherwise a new section will be created.

       If --auto is given gbp 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 gbp dch at which
       point it should start in the Git history.

       The additional path arguments can be used to restrict the repository paths gbp  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 version number is being auto incremented
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.

--distribution=name
Set the distribution field to name.

--force-distribution
Force the distribution specified with --distribution to be used, even if it doesn't
match the list of known distributions.

--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
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  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 -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:

Git-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).

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

Git-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)

CONFIGURATION FILES

       Several gbp.conf files are parsed to set defaults for the above commandline arguments. See
       the gbp.conf(5) manpage for details.

AUTHOR

       Guido Guenther <agx@sigxcpu.org>

                                         15 February 2014                              GBP-DCH(1)