git-dch

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] [--[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.

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

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 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 gbp.conf(5) 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 Cl2vcs,

AUTHOR

Guido Guenther