The &changelog; gives the &debian; package a version number and keeps track of changes made to the package in a particular version. While the changelog can still be maintained by hand we can make use of &gbp-dch; to have our &git; commit messages end up in &changelog;. This avoids the double maintenance of the &git; commit history and the &debian; changelog. If you don't want a one to one mapping of changelog entries to &git; commits you're free to edit the changelog by hand at any point. Not committing changelog entries with the actual modifications also has the advantage that the changelog won't cause any trouble when cherry-picking patches from different branches. It can be created when releasing the package or after performing several commits. Invocations of &dch; and &gbp-dch; can be mixed. 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 editing. You can run &gbp-dch; without any options to make it add all commit messages since the last &debian; tag to a new UNRELEASED changelog section: &gbp-dch; You can then commit the debian/changelog to have your current changes recorded. Later invocations of &gbp-dch; will check when debian/changelog was last modified and not add these commits again. Upon your last call of &gbp-dch; before releasing the package add --release again to have the UNRELEASED distribution in the changelog turned into unstable. The downside of the above methods is that you either have the version number of the last release in &changelog; or that you have a changelog entry with UNRELEASED that has the same version number for all commits you do during the development cycle of your package. Although this is common practice in &debian; it means that also all your test builds have the same version number which makes them hard to distinguish in e.g. continuous integration pipelines. To address these shortcomings &gbp-dch; has a --snapshot option that can be used to create (unreleased) snapshots for intermediate testing with a version number that is lower than the one of the final package: &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 banner contains the commit id of the current branch HEAD, &gbp-dch; can figure out what to append to the changelog by itself (even without committing the changelog first): &gbp-dch; --snapshot will fetch the commit id from &changelog; 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; --release This will pick new commit if present and remove the specially crafted version number and the snapshot header. If you want finer control of what is being added you can again use the --since. 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] You can use --full to include the full commit message in the changelog. If you want to tweak the formatting there's a --customizations. 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.