--- name: "gbp-dch" section: "1" platform: "linux" package: "git-buildpackage" version: "0.9.38" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gbp-dch" --- # gbp-dch(1) Generate the debian/changelog from Git commit history ## NAME gbp-dch - Generate the debian/changelog from Git commit history ## SYNOPSIS FC**gbp dch**F\[0\] \[FC**--version**F\[0\]\] \[FC**--help**F\[0\]\] \[FC**--verbose**F\[0\]\] \[FC**--color=**F\[0\]\[auto\|on\|off\]\] \[FC**--color-scheme=**F\[0\] *COLOR\_SCHEME*\] \[FC**--debian-branch=**F\[0\] *branch\_name*\] \[FC**--debian-tag=**F\[0\] *tag-format*\] \[FC**--upstream-branch=**F\[0\] *branch\_name*\] \[FC**--upstream-tag=**F\[0\] *tag-format*\] \[FC**--ignore-branch**F\[0\]\] \[FC**-s**F\[0\] *commit-ish* \| FC**--since=**F\[0\] *commit-ish*\] \[\[FC**-S**F\[0\] \| FC**--snapshot**F\[0\]\] \| \[FC**-R**F\[0\] \| FC**--release**F\[0\]\]\] \[FC**-N**F\[0\] *version* \| FC**--new-version=**F\[0\] *version*\] \[FC**--bpo**F\[0\] \| FC**--nmu**F\[0\] \| FC**--qa**F\[0\] \| FC**--security**F\[0\] \| FC**--team**F\[0\] \| FC**--local=**F\[0\] *suffix*\] \[FC**--distribution=**F\[0\] *name*\] \[FC**--force-distribution**F\[0\]\] \[FC**-U**F\[0\] *level* \| FC**--urgency=**F\[0\] *level*\] \[FC**--\[no-\]full**F\[0\]\] \[FC**--\[no-\]meta**F\[0\]\] \[FC**--meta-closes=bug-close-tags**F\[0\]\] \[FC**--meta-closes-bugnum=bug-number-format**F\[0\]\] \[FC**--snapshot-number=**F\[0\] *expression*\] \[FC**--id-length=**F\[0\] *number*\] \[FC**--git-log=**F\[0\] *git-log-options*\] \[FC**--\[no-\]git-author**F\[0\]\] \[FC**--\[no-\]multimaint**F\[0\]\] \[FC**--\[no-\]multimaint-merge**F\[0\]\] \[FC**--spawn-editor=\[always\|never\|snapshot\|release\]**F\[0\]\] \[FC**--commit-msg=**F\[0\] *msg-format*\] \[FC**-c**F\[0\] \| FC**--commit**F\[0\]\] \[FC**--customizations=**F\[0\] *customization-file*\] \[FC**--postedit=**F\[0\] *COMMAND*\] \[FC**--dch-opt=**F\[0\] *dch-options*\]... \[FC**--verbose**F\[0\]\] *path1 path2* ## DESCRIPTION **gbp dch** reads git commit messages and generates the Debian changelog from it. It starts at a given commit specified by the FC**--since**F\[0\] option up to the current *HEAD*. For each commit found it adds the commit message to the changelog. If FC**--since**F\[0\] is not given the commit to start from is determined by the following rules (first one matches): - 1\. The start commit is read from the snapshot banner (see below for details) - 2\. If the topmost version of the FC*debian/changelog*F\[0\] is already tagged. Use the commit the tag points to as start commit. - 3\. The last commit that modified FC*debian/changelog*F\[0\] is used as start commit. This is called automatic mode. If the distribution of the topmost section in FC*debian/changelog*F\[0\] is *UNRELEASED*, the changelog entries will be inserted into this section. Otherwise a new section will be created. If one or more paths are given as arguments **gbp dch** will only include changes in FC*debian/changelog*F\[0\] 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 FC*debian/changelog*F\[0\]. To restrict the selected changes even further you can use use the FC**--git-log**F\[0\] option which is passed on verbatim to **git log**. E.g. by using FC**--git-log=**F\[0\]*"--author=Foo* *Bar"*. The above relies on the FC**--debian-branch**F\[0\] option pointing to the current branch and FC**--upstream-branch**F\[0\] 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 FC**--upstream-tag**F\[0\] and FC**--debian-tag**F\[0\] 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). If not changelog exists yet it is created and the version number is derived from the last upstream tag if found. ## OPTIONS - FC**--version**F\[0\] Print version of the program, i.e. version of the git-buildpackage suite - FC**-v**F\[0\], FC**--verbose**F\[0\] Verbose execution - FC**-h**F\[0\], FC**--help**F\[0\] Print help and exit - FC**--color=**F\[0\]\[auto\|on\|off\] Whether to use colored output. - FC**--color-scheme=**F\[0\]*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, FC**--git-color-scheme=**F\[0\]FC'cyan:34::'F\[0\] would show debug messages in cyan, info messages in blue and other messages in default (i.e. warning and error messages in red). - FC**--debian-branch**F\[0\]=*branch\_name* The branch in the Git repository the Debian package is being developed on, default is *master*. - FC**--upstream-branch**F\[0\]=*branch\_name* Branch to determine the upstream version from. Default is *upstream*. - FC**--git-upstream-tag=**F\[0\]*TAG-FORMAT* Use this tag format when looking for tags of upstream versions, default is *upstream/%(version)s*. - FC**--ignore-branch**F\[0\] Don't check if the current branch matches *debian-branch*. - FC**--debian-tag=**F\[0\]*tag-format* Tag format used, when tagging debian versions, default is *debian/%(version)s* - FC**--since=**F\[0\]*commit-ish* Start reading commit messages at *commit-ish*. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--auto**F\[0\], FC**-a**F\[0\] This option is ignored for compatibility with older versions. It used to trigger automatic mode. - FC**--\[no-\]meta**F\[0\] Parse meta tags like FC**Closes:**F\[0\], FC**Thanks:**F\[0\] and FC**Gbp-Dch:**F\[0\]. See META TAGS below. - FC**--meta-closes=**F\[0\]*bug-close-tags* What meta tags to look for to generate bug-closing changelog entries. The default is FC'Closes\|LP'F\[0\] to support Debian and Launchpad. - FC**--meta-closes-bugnum=**F\[0\]*bug-number-format* What regular expression should be used to parse out the bug number. The default is FC'(?:bug\|issue)?\\#?\\s?\\d+'F\[0\]. Note: the regex should suppress all portions of the bug number that are not wanted using FC"(?:)"F\[0\], see Python regex manual for details. Example: FC**--meta-closes-bugnum=**F\[0\]FC"(?:bug)?\\s\*ex-\\d+"F\[0\] would match all of the following: ``` FC Possible Txt Match? Result ------------ ------ ------ bug EX-12345 Y EX-12345 ex-01273 Y ex-01273 bug ex-1ab Y ex-1 EX--12345 NF[0] ``` - FC**--\[no-\]full**F\[0\] Include the full commit message in the changelog output. - FC**--snapshot**F\[0\], FC**-S**F\[0\] Create a snapshot release entry. It uses a snapshot release number which is smaller than the final release number and adds a warning banner to the changelog entry. The version number is being auto incremented with every new snapshot release. The snapshot banner is also used by **gbp dch** to determine which entries are already in the changelog. This prevents duplicated entries in FC*debian/changelog*F\[0\] when you did not commit the changelog yet. - FC**--snapshot-number=**F\[0\]*expression* Python expression that gets eval()ed to the new snapshot number. - FC**--release**F\[0\], FC**-R**F\[0\] Remove any snapshot release banners and version suffixes (if any), set the current distribution to *unstable*, and open the changelog for final tweaking. This option can't be set via FC*gbp.conf*F\[0\]. It's usually used to finalize the changelog before making a release. - FC**--new-version=**F\[0\]*version*, FC**-N**F\[0\] *version* Add a new changelog section with version *newversion*. Together with FC**--snapshot**F\[0\], the snapshot number will be appended to *newversion*. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--team**F\[0\] Create a Team upload changelog entry. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--bpo**F\[0\] Increment the Debian release number for an upload to backports, and add a backport upload changelog comment. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--nmu**F\[0\] Increment the Debian release number for a non-maintainer upload. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--qa**F\[0\] 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 FC*gbp.conf*F\[0\]. - FC**--security**F\[0\] 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 FC*gbp.conf*F\[0\]. - FC**--local=**F\[0\]*suffix*, FC**-l**F\[0\] *suffix* Increment the Debian release number for a local build using the specified suffix. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--distribution=**F\[0\]*name* Set the distribution field to *name*. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--force-distribution**F\[0\] Force the distribution specified with FC**--distribution**F\[0\] to be used, even if it doesn't match the list of known distributions. This option can't be set via FC*gbp.conf*F\[0\]. - FC**--urgency=**F\[0\]*level* Set the urgency field to *level*. - FC**--git-log=**F\[0\]*git-log-options* Options passed on verbatim to [git-log(1)](/git-log/1.md). - FC**--id-length=**F\[0\]*N* Include *N* digits of the commit id in the changelog entry. Default is to not include any commit ids at all. - FC**--ignore-regex=**F\[0\]*regex* Ignore commit lines matching *regex* when generating the changelog. - FC**--git-author**F\[0\] Use user.name and user.email from [git-config(1)](/git-config/1.md) for changelog trailer. - FC**--\[no-\]multimaint-merge**F\[0\] This option is passed verbatim to [dch(1)](/dch/1.md) and is enabled by default. - FC**--spawn-editor=**F\[0\]*\[always\|never\|snapshot\|release\]* Whether to spawn an editor: always, never, when doing snapshots or when doing a release. - FC**--commit-msg=**F\[0\]*msg-format* Use this format string for the commit message when committing the generated changelog file (when FC**--commit**F\[0\] is given). Default is *Update changelog for %(version)s release* - FC**--commit**F\[0\] Commit the generated changelog. - FC**--customizations=**F\[0\]*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. - FC**--postedit=**F\[0\]*COMMAND* Run*COMMAND* after changes to the changelog file have been finalized, That is, after dch has been run and possible text editor has been exited, but, before changes are (possibly) committed to git. - FC**--dch-opt=**F\[0\]*dch-option* Pass option to dch verbatim. Note that **gbp dch** invokes dch multiple times and the option is passed to all invocations so not all dch options make sense here. Options may also conflict with options picked by **gbp dch**. ## 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 FC**--snapshot**F\[0\] or FC**-S**F\[0\], **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** FC**-S**F\[0\] so that later snapshots automatically have a higher version number. To leave snapshot mode, invoke **gbp dch** with the FC**--release**F\[0\] 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 FC*debian/changelog*F\[0\] can be modified by special tags (called Meta Tags) given in the git commit message. Meta Tag processing can be activated via the FC**--meta**F\[0\] option. The tags must start at the first column of a commit message but can appear on any line. They are of the form FC**Tagname**F\[0\]: *value*. Valid Meta Tags are: - FC**Gbp-Dch**F\[0\]: *action* Supported actions are: *Ignore* which will ignore this commit when generating FC*debian/changelog*F\[0\], *Short* which will only use the description (the first line) of the commit message when generating the changelog entry (useful when FC**--full**F\[0\] is given), and *Full* which will use the full commit message when generating the changelog entry (useful when FC**--full**F\[0\] is not given). In addition to FC**Gbp-Dch**F\[0\], the deprecated FC**Git-Dch**F\[0\] is still supported. - FC**Thanks**F\[0\]: *msg* Add a thanks message after the commit message. - FC**Closes**F\[0\]: *bugnumber* Indicate in the FC*debian/changelog*F\[0\] that the bug was closed by this commit. See the FC**--meta-closes**F\[0\] on how to extend this for other bugtrackers. The following git commit message: ``` FC Document meta tags so one doesn't have to consult the manual Gbp-Dch: Short Closes: #636088 Thanks: Raphaël Hertzog for the suggestionF[0] ``` Results in this FC*debian/changelog*F\[0\] entry: ``` FC * Document meta tags. Thanks to Raphaël Hertzog for the suggestion (Closes: #636088)F[0] ``` ## EXAMPLES Update the latest FC*debian/changelog*F\[0\] so package is ready for release, and commit the change. A editor will be spawned so the entry can be reviewed and manually refined easily. ``` FC gbp dch --release --commitF[0] ``` Right after running **git import-orig --uscan**, create a new FC*debian/changelog*F\[0\] entry for UNRELEASED, and include only commits that modified something in the FC*debian/*F\[0\] subdirectory so all upstream commits are ignored: ``` FC gbp dch --distribution=UNRELEASED \ --commit --commit-msg="Update changelog after new upstream version import" \ -- debianF[0] ``` ## CONFIGURATION FILES Several FC*gbp.conf*F\[0\] files are parsed to set defaults for the above command-line 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 ⟨file:///usr/share/doc/git-buildpackage/manual-html/index.html⟩\ Cl2vcs ⟨https://honk.sigxcpu.org/cl2vcs⟩ , ## AUTHOR Guido Günther \