--- name: "git-dch" section: "1" platform: "linux" package: "git-buildpackage" version: "0.6.22" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/gbp-dch" --- # git-dch(1) Generate the Debian changelog from git commit messages Part of [gbp-dch(1)](/gbp-dch/1.md). ## 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 '\:\:\:\'. 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)](/git-log/1.md). - **--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)](/git-config/1.md) 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 *~\.gbp\*. 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: - **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)](/gbp.conf/5.md) manpage for details. ## SEE ALSO [**gbp-buildpackage**(1)](/gbp-buildpackage/1.md), [**gbp-import-dsc**(1)](/gbp-import-dsc/1.md), [**gbp-import-dscs**(1)](/gbp-import-dscs/1.md), [**gbp-import-orig**(1)](/gbp-import-orig/1.md), [**gbp.conf**(5)](/gbp.conf/5.md), [**debuild**(1)](/debuild/1.md), [**git**(1)](/git/1.md), [**pristine-tar**(1)](/pristine-tar/1.md), *The Git-Buildpackage Manual* \ *Cl2vcs* \, ## AUTHOR Guido Guenther \