Releases and Snapshots

Table of Contents
Customizing snapshot numbers
More on commit messages

When branching and merging frequently, the different Debian changelog entries on the different branches tend to get into the way of the automatic merge and the the merge fails—leaving the (pathological) merge to the committer. In order to avoid this, gbp dch offers a way for creating changelog entries from Git commits before doing a release or anytime between releases.

The simplest way is doing all the changes to the debian-branch without touching debian/changelog at all. Then, when done, do:

gbp dch --release

This will look up the latest released version in the changelog, increment the version in the Debian changelog, generate changelog messages from the corresponding Git commit id up to the branch head, and finally spawns an editor for final changelog file editing by invoking dch --release.

But what if you want to have an (unreleased) snapshot for intermediate testing:

gbp dch --snapshot

will generate a snapshot release with a specially crafted version number and a warning in the changelog that this is a snapshot release:

git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low

  ** SNAPSHOT build @470ce29ec7877705c844474a2fd89869aea0406d **

  * add support for automatic snapshot

During subsequent calls with --snapshot, this version number will continue to increase. Since the snapshot banners contains the commit id of the current branch head, gbp dch can figure out what to append to the changelog by itself:

gbp dch --snapshot --auto

will fetch the commit id and add changelog entries from that point to the current HEAD—again auto incrementing the version number. If you don't want to start at that commit id, you can specify any id or tag with:

gbp dch --since=e76a6a180a57701ae4ae381f74523cacb3152780 --snapshot

After testing, you can remove the snapshot header by a final gbp dch call:

gbp dch --since=HEAD --release

This will add no further entries but simply remove the specially crafted version number and the snapshot header. Again you can use any commit id or tag instead of HEAD if you want to add further changelog entries—or you can (of course) use --auto again.

Customizing snapshot numbers

If the auto incrementing of the snapshot number doesn't suite your needs, you can give any Python expression that evaluates to a positive integer to calculate the new snapshot number:

gbp dch -S -a --snapshot-number=1
gbp dch -S -a --snapshot-number='snapshot + 2'
gbp dch -S -a --snapshot-number='os.popen("git-log --pretty=oneline | wc -l").readlines()[0]'
gbp dch -S -a --snapshot-number=`git-log --pretty=oneline debian/0.3.3 | wc -l`

You can also add the snapshot-number calculation to gbp.conf:

[DEFAULT]
snapshot-number = os.popen("git-log --pretty=oneline | wc -l").readlines()[0]

More on commit messages

You can use --full to include the full commit message in the changelog; note that you will lose the formatting though, since dch wraps lines by itself.

Additionally, there are tags Closes: and Thanks: available to customize the commit message. Each tag has to start at the beginning of a single line. For example, the git commit message

New upstream version

Closes: #1000
Thanks: cool upstream

would result in a changelog entry:

    * New upstream version (Closes: #1000) - thanks to cool upstream

You can use the Closes: tag multiple times.

There are several tags to further customize what (and how) commit messages get included into the changelog:

To exclude a commit from the generated changelog, use:

Gbp-Dch: Ignore

This is e.g. useful if you're just fixing up a previous commit and couldn't amend it, or for other janitorial commits that really don't need to end up in the changelog. For example, the following git commit message

Set correct branchnames in debian/gbp.conf

Gbp-Dch: Ignore

will not show up in the generated changelog in any way.

To include the full commit message in the changelog, use:

Gbp-Dch: Full

To only include the short description in the changelog and skip the body, use:

Gbp-Dch: Short

The latter only takes effect when running gbp dch with the --full option since including only the short description is the default.

Usually, changelog entries should correspond to a single Git commit. In this case, it's convenient to include the commit id in the changelog entry. This has the advantage that it's easy for people to identify changes without having to write very extensive changelog messages—the link back to Git can be automated via the Vcs-Browser and Vcs-Git fields in debian/control. See Cl2vcs for how this looks.

The inclusion of the commit id can be done automatically via gbp dch's --id-length option. Using --id-length=7 would change the above example to:

    * [571bfd4] New upstream version (Closes: #1000) - thanks to cool upstream

This makes it much easier to see which commit actually fixed bug #1000.