NAME¶
git-dch;, gbp-dch; - Generate the Debian changelog from git commit messages
SYNOPSIS¶
gbp dch [
--version ] [
--help ] [
--verbose ] [
--color= [auto|on|off] ] [
--color-scheme=COLOR_SCHEME ] [
--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 ] [
--customizations= 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¶
- --version
- Print version of the program, i.e. version of the
git-buildpackage suite
- -v
- --verbose
- Verbose execution
- -h
- --help
- Print help and exit
- --color=[auto|on|off]
- Whether to use colored output.
- --color-scheme=COLOR_SCHEME
- 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).
- --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.
- --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.
- --customizations=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.
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.
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.
SEE ALSO¶
gbp-buildpackage(1),
gbp-import-dsc(1),
gbp-import-dscs(1),
gbp-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>