gbp-dch

&dhsection;

gbp-dch

Generate the &debian; changelog from git commit messages

          &gbp-dch;
          &man.common.options.synopsis;
          --debian-branch=branch_name
          --debian-tag=tag-format
          --upstream-branch=branch_name
          --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

&man.common.options.description;

`--debian-branch`=`branch_name`

- The branch in the Git repository the Debian package is being developed on, default is `master`.

`--upstream-branch`=`branch_name`

- Branch to determine the upstream version from. Default is `upstream`.

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

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

`Gbp-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).

  Insteaad of `Gbp-Dch` the deprecated `Git-Dch` is still supported.

`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

          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.gbp.buildpackage, man.gbp.import.dsc, man.gbp.import.dscs, man.gbp.import.orig, man.gbp.conf, &man.seealso.common; Cl2vcs,

## AUTHOR

&dhusername; &dhemail;