NAME¶
git-dch - Generate the Debian changelog from git commit messages
SYNOPSIS¶
git-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 ] [
--[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¶
git-dch reads git commit messages and generates the Debian changelog from
it. If no arguments are given
git-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
git-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
git-dch at which point it should
start in the Git history.
The additional path arguments can be used to restrict the repository paths
git-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 autoincremented 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.
- --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]-multimaintmerge
- 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 git-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
git-dch
-S so that later snapshots automatically have a higher version number.
To leave snapshot mode invoke
git-dch with the
--release option.
This removes the pseudo heaader 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 howto 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 [XRef to GBP.MAN.GBP.CONF] manpage for details.
SEE ALSO¶
git-buildpackage(1),
git-import-dsc(1),
git-import-dscs(1),
git-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>