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

    	  -S
              --snapshot

    	  -R
              --release

    	  -a
              --auto

    	  -s commitish
              --since=commitish

    	-N version
    	--new-version=version

            --bpo
            --nmu
            --qa
            --security
            --team

          --distribution=name
          --force-distribution

    	-U level
    	--urgency=level

          --[no-]full
          --[no-]meta
          --meta-closes=bug-close-tags
          --meta-closes-bugnum=bug-number-format
          --snapshot-number=expression
          --id-length=number
          --git-log=git-log-options
          --[no-]git-author
          --[no-]multimaint
          --[no-]multimaint-merge
          --spawn-editor=[always|never|snapshot|release]
          --commit-msg=msg-format

    	-c
    	--commit

          --customizations=customization-file
          --verbose
          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 commit corresponding to 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.

If one ore more paths are given as arguments &gbp-dch; will only include changes in `debian/changelog` that affect these paths. E.g. using debian/ is a good choice if upstream uses &git; and you don't want the upstream history to end up in `debian/changelog`.

To restrict the selected changes even further you can use use the `--git-log` option which is passed on verbatim to `git log`. E.g. by using `--git-log=``"--author=Foo Bar"`.

The above relies on the `--debian-branch` option pointing to the current branch and `--upstream-branch` pointing to the corresponding upstream branch in order to find the right merge points of these branches. Furthermore &gbp-dch; must be able to identify git tags from upstream and Debian version numbers. If you're not using the defaults check the `--upstream-tag` and `--debian-tag` options and make sure they match the tags created by e.g. &gbp-import-orig (when using tarballs) or upstream's tagging pattern (when using upstream's git directly).

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

`--git-upstream-tag=``TAG-FORMAT`

- use this tag format when looking for tags of upstream versions, default is `upstream/%(version)s`.

`--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`. This option can't be set via &gbp.conf;.

`--auto`, `-a`

- Guess the last commit documented in the changelog from the snapshot banner (or from the last tag if no snapshot banner exists). This option can't be set via &gbp.conf;.

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

`--meta-closes-bugnum=``bug-number-format`

- What regular expression should be used to parse out the bug number. The default is `'(?:bug|issue)?\#?\s?\d+'`. Note: the regex should suppress all portions of the bug number that are not wanted using `"(?:)"`, see Python regex manual for details.

  Example: `--meta-closes-bugnum=``"(?:bug)?\s*ex-\d+"` would match all of the following:

                       Possible Txt  Match?    Result
                       ------------  ------    ------
                       bug EX-12345    Y       EX-12345
                       ex-01273        Y       ex-01273
                       bug ex-1ab      Y       ex-1
                       EX--12345       N

`--[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. This option can't be set via &gbp.conf;.

`--new-version=``version`, `-N` `version`

- Add a new changelog section with version `newversion`. Together with `--snapshot`, the snapshot number will be appended to `newversion`. This option can't be set via &gbp.conf;.

`--team`

- Create a Team upload changelog entry. This option can't be set via &gbp.conf;.

`--bpo`

- Increment the Debian release number for an upload to backports, and add a backport upload changelog comment. This option can't be set via &gbp.conf;.

`--nmu`

- Increment the Debian release number for a non-maintainer upload. This option can't be set via &gbp.conf;.

`--qa`

- Increment the Debian release number for a Debian QA Team upload, and add a QA upload changelog comment. This option can't be set via &gbp.conf;.

`--security`

- Increment the Debian release number for a Debian Security Team non-maintainer upload, and add a "Security Team upload" changelog comment. This option can't be set via &gbp.conf;.

`--distribution=``name`

- Set the distribution field to `name`. This option can't be set via &gbp.conf;.

`--force-distribution`

- Force the distribution specified with `--distribution` to be used, even if it doesn't match the list of known distributions. This option can't be set via &gbp.conf;.

`--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|never|snapshot|release]``

- Whether to spawn an editor: always, never, 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).

  In addition to `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;