gbp-dch(1)

📦
version 0.9.43 · 6 versions
, in ubuntu stonking

✨ NAME ✨

okay so welcome to gbp-dch(1), straight out of the git-buildpackage manual 🌸 this is the tool that generates your debian/changelog from your Git commit history, and honestly? she eats. let's get into it 💅

gbp-dch — Generate the debian/changelog from Git commit history 🦋

🎀 SYNOPSIS 🎀

gbp dch [--version] [--help] [--verbose] [--color=[auto|on|off]]
        [--color-scheme= COLOR_SCHEME] [--debian-branch= branch_name]
        [--debian-tag= tag-format] [--upstream-branch= branch_name]
        [--upstream-tag= tag-format] [--ignore-branch] [-s commit-ish |
        --since= commit-ish] [[-S | --snapshot] | [-R | --release]] [-N
        version | --new-version= version] [--bpo | --nmu | --qa |
        --security | --team | --lts | --stable | --local= suffix]
        [--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] [--postedit= COMMAND] [--dch-opt= dch-options]...
        [--verbose] path1 path2

💖 DESCRIPTION 💖

so like, gbp dch reads your git commit messages and literally builds the Debian changelog out of them 🫶 she starts at whatever commit you tell her with --since and walks all the way up to the current HEAD. every commit she finds? her message gets added to the changelog. periodt.

if you don't give her --since, she figures out the starting commit herself using these rules (and she takes the first one that matches, no debate):

  1. the start commit gets read from the snapshot banner (more on that below, bestie)
  2. if the topmost version of the debian/changelog is already tagged → she uses whatever commit that tag points to as the start commit
  3. otherwise the last commit that modified debian/changelog becomes the start commit

this whole lil auto-deduction thing? it's called automatic mode ✨ iconic behaviour tbh

now 👀 if the distribution of the topmost section in debian/changelog is UNRELEASED, your changelog entries get inserted right into that section. if it's literally anything else, she creates a brand new section for you.

if you pass one or more paths as arguments, gbp dch will only include changes in debian/changelog that affect those paths. like, throwing debian/ in there is a whole vibe if upstream uses Git and you do not want their whole history showing up in your debian/changelog 🙈

want to restrict things even more? use the --git-log option — it gets passed on verbatim to git log. for example: --git-log="--author=Foo Bar" and boom, only Foo Bar's commits 🎀

all of the above relies on --debian-branch pointing at your current branch and --upstream-branch pointing at the corresponding upstream branch, so she can find the right merge points between them. and also, gbp dch has to be able to identify git tags from upstream and Debian version numbers. so if you're not running the defaults, please check --upstream-tag and --debian-tag and make sure they actually match the tags created by, like, gbp import-orig (if you're using tarballs) or upstream's own tagging pattern (if you're using upstream's git directly). trust me, check them 👑

and lastly: if no changelog exists yet? she creates one for you. and the version number gets derived from the last upstream tag if she can find one 💜

💅 OPTIONS 💅

strap in, there are a lot of them, and every single one is here, no cap.

  • --version — prints the version of the program, aka the version of the whole git-buildpackage suite ✨
  • -v, --verbose — verbose execution. she tells you everything she's doing 🗣️
  • -h, --help — print help and exit, the classic 🫶
  • --color=[auto|on|off] — whether to use colored output or not 🌈
  • --color-scheme=COLOR_SCHEME — which colors to use in the output (only when color is enabled, obvi). the format for COLOR_SCHEME is '<debug>:<info>:<warning>:<error>'. numerical values and color names both work, and empty fields just mean "use 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). cute, right? 💙
  • --debian-branch=branch_name — the branch in the Git repo where the Debian package is being developed. default is master.
  • --upstream-branch=branch_name — the branch used 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. living dangerously, love that for you 💀
  • --debian-tag=tag-format — the tag format used when tagging debian versions. default is debian/%(version)s.
  • --since=commit-ish — start reading commit messages at commit-ish. heads up: this option can't be set via gbp.conf ⚠️
  • --auto, -a — this option is ignored, it's only there for compatibility with older versions. it used to trigger automatic mode, back in the day.
  • --[no-]meta — parse meta tags like Closes:, Thanks: and Gbp-Dch:. see META TAGS below for the tea 👀
  • --meta-closes=bug-close-tags — which meta tags to look for when generating bug-closing changelog entries. the default is 'Closes|LP', so both Debian and Launchpad are supported 💖
  • --meta-closes-bugnum=bug-number-format — which regular expression to use when parsing out the bug number. the default is '(?:bug|issue)?\#?\s?\d+'. note: the regex should suppress all portions of the bug number you don't want by using "(?:)" — go read the Python regex manual for the details, iykyk.

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. the whole thing, not just the subject line 🌸
  • --snapshot, -S — create a snapshot release entry. it uses a snapshot release number that's smaller than the final release number, and it slaps a warning banner onto the changelog entry. the version number gets auto-incremented with every new snapshot release 🔥

the snapshot banner is also what gbp dch uses to figure out which entries are already in the changelog. this is what stops you from getting duplicated entries in debian/changelog when you haven't committed the changelog yet. she's looking out for you 🫶

  • --snapshot-number=expression — a Python expression that gets eval()ed to produce the new snapshot number. yes, eval(). yes, that's really what it does.
  • --release, -R — removes any snapshot release banners and version suffixes (if any), sets the current distribution to unstable, and opens the changelog up for final tweaking 💅 this option can't be set via gbp.conf. it's usually what you reach for to finalize the changelog right before making a release.
  • --new-version=version, -N version — add a new changelog section with version newversion. if you combine it with --snapshot, the snapshot number gets 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 🔒
  • --lts — increment the Debian release number for a Debian LTS Team upload, and add a LTS upload changelog comment. this option can't be set via gbp.conf.
  • --stable — increment the Debian release number for an upload to the current stable release. this option can't be set via gbp.conf.
  • --local=suffix, -l suffix — increment the Debian release number for a local build, using the suffix you specify. 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 you gave to --distribution to actually 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). verbatim means verbatim, bestie.
  • --id-length=N — include N digits of the commit id in the changelog entry. by default she doesn't 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 the changelog trailer 👑
  • --[no-]multimaint-merge — this option gets passed verbatim to dch(1) and is enabled by default.
  • --spawn-editor=[always|never|snapshot|release] — whether to spawn an editor: always, never, only when doing snapshots, or only when doing a release. your call 🌸
  • --commit-msg=msg-format — use this format string for the commit message when committing the generated changelog file (only relevant when --commit is given). the default is Update changelog for %(version)s release ✨
  • --commit — commit the generated changelog. she'll do it for you 💅
  • --customizations=customization-file — load Python code from customization-file. right now the only genuinely useful thing that code can do is define a custom format_changelog_entry() function.
  • --postedit=COMMAND — run COMMAND after changes to the changelog file have been finalized. and by finalized i mean: after dch has been run and any possible text editor has been exited, but before changes are (possibly) committed to git. timing is everything, fr fr ⏰
  • --dch-opt=dch-option — pass an option to dch verbatim. note: gbp dch invokes dch multiple times and the option gets passed to all the invocations, so not all dch options make sense here. and some of them may straight up conflict with options that gbp dch itself picked. you've been warned 🙈

more of this page incoming bestie, don't go anywhere 🦋

✨ SNAPSHOT MODE ✨

Ok bestie, this one is so handy for when you're doing quick test-and-install cycles and you literally cannot be bothered to think about version numbers or write changelog entries. Snapshot mode has your back. 🫶

So when you use --snapshot or -S, gbp dch sticks 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>. 💅

And the cute part? It automatically increments the snapshot number on subsequent invocations of gbp dch -S, so later snapshots automatically get a higher version number. No manual bumping, no drama. ✨

To leave snapshot mode, just invoke gbp dch with the --release option. That removes the pseudo header and unmangles the version number so the released version has a higher version number than the snapshots. Iconic behaviour, honestly. 👑

🏷️ META TAGS 🏷️

Additional to the above options, the formatting of the commit message in debian/changelog can be modified by special tags (they're called Meta Tags) that you drop right into the git commit message. Meta Tag processing gets activated via the --meta option. 🌸

Rules of the game:

  • The tags must start at the first column of a commit message, but they can appear on any line.
  • They're 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 (super useful when --full is given)
    • Full — which will use the full commit message when generating the changelog entry (super useful when --full is not given)

In addition to Gbp-Dch, the deprecated Git-Dch is still supported. (Deprecated, bestie — it still works, but don't go building your whole personality around it. 💀)

  • Thanks: msg — add a thanks message after the commit message. Being nice is free, periodt. 🎀
  • 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.

So like, this 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)

Look at that. Gorgeous. It's giving automation with taste. 🦋

🌈 EXAMPLES 🌈

Update the changelog for release

Update the latest debian/changelog so the package is ready for release, and commit the change. An editor will be spawned so the entry can be reviewed and manually refined easily. ✍️

gbp dch --release --commit

Changelog after a new upstream import

Right after running git import-orig --uscan, create a new debian/changelog entry for UNRELEASED, and include only commits that modified something in the debian/ subdirectory so all upstream commits are ignored: 🙈

gbp dch --distribution=UNRELEASED \
--commit --commit-msg="Update changelog after new upstream version import" \
-- debian

The -- debian is doing main character energy work there, ngl. 🔥

🧚 CONFIGURATION FILES 🧚

Several gbp.conf files are parsed to set defaults for the above command-line arguments. See the gbp.conf(5) manpage for the details, bestie. 💜

👑 SEE ALSO 👑

💖 AUTHOR 💖

Guido Günther <agx@sigxcpu.org>

And that's the whole thing, babes — this page is dated 26 May 2026 and belongs to gbp-dch(1). Go forth and write changelogs like the icon you are. 💅✨🎀

📦 where this page comes from