When upstream uses Git

If upstream uses Git™ for development (and you don't want to ignore that fact entirely), there are at least three ways to handle packaging. The first one uses Git™ exclusively and creates the upstream tarballs from the upstream tag while the second one still uses upstream tarballs but links your packaging Git™ history with upstreams Git™ history. The third one also uses a tarballs but does not link to the upstream history.

No upstream tarballs

If upstream doesn't build upstream tarballs, or you don't care about them, the simplest way is to clone upstream's repository and create a separate packaging branch in there. You will not need gbp import-orig at all with this workflow. gbp buildpackage will handle creating the upstream tarballs needed for the Debian source package.

For that to work you need to tell gbp what the upstream tag format looks like. Therefore you either use the --git-upstream-tag command line option or the upstream-tag configuration file variable to specify upstream's tag format.

For example a common upstream format is to put a v in front of the version number. In this case, the configuration option would look like:

upstream-tag = v%(version)s

version will be replaced by gbp with the upstream version number as determined from debian/changelog. The %()s might be familiar from Python format strings. The option was placed in the [DEFAULT] section instead of the [buildpackage] section of the configuration so other tools like gbp dch make use of it too.

Some upstreams use other formats though and don't separate numbers by dots but rather by underscore(_), hyphen(-) or anything else. In order to cope with that you can use version mangling of these characters via substitution. The substitution works as follows:

upstream-tag = v%(version%.%_)s

This means that each occurrence of . will be replaced by _ in the upstream version number. For example the upstream version 1.2.3 as determined from the debian/changelog will be looked up as Git™ tag v1_2_3 by gbp buildpackage.

If you want the substitution to be the % character you have to escape it. E.g. %(version%-%\%)s will replace - with %, transforming 1-A.B.C to 1%A.B.C. Only a single replacement is supported and it can only replace a single character.

Since some of the possible mangling characters like _ and % are also used to denote epochs and tilde revisions these versions can't be reconstructed when mapping from Git™ tags back to Debian™ versions and will therefore break other tools like gbp dch. So use version mangling with care. It's better to come up with a Debian compatible tag format upstream. See DEP-14 for the currently used expansion rules for Debian version numbers.

If you're using pristine-tar™ you can make gbp buildpackage commit the generated tarball back to the pristine-tar branch using the --git-pristine-tar-commit option or you can use gbp pristine-tar after you've created the tarballs. This will make sure others building your package can exactly regenerate the tarball you created when building the Debian™ package.

Step by step

To not make any assumptions about gbp's configuration, the following steps have all options given in its long versions on the command line. You can add these to gbp.conf to save lots of typing.

First, we clone the upstream repository. To avoid any ambiguities between the Debian™ packaging repository and the upstream repository, we name the upstream repository upstream instead of the default origin.

  git clone --no-checkout -o upstream git://git.example.com/libgbp.git
  cd libgbp
  git checkout -b debian/sid v1.0

The above makes sure we have debian/sid for the Debian™ packaging. We didn't create any upstream/* branches; they're not needed for the packaging and only need to be kept up to date. We started the branch at the commit corresponding to the tag v1.0.

After adding the Debian™ packaging, we build the package. This assumes you're using pristine-tar™ and upstream uses a version number format as described above:

  gbp buildpackage --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid

When updating to a new upstream version, we simply fetch from upstream and merge in the new tag. Afterwards, we update the changelog and build the package:

  git fetch upstream
  git merge v1.1
  gbp dch --debian-branch=debian/sid --snapshot --auto debian/
  gbp buildpackage --git-ignore-new --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s'

Note that the above gbp dch call makes sure we only pickup changes in the debian/ directory. Since we told it to build a snapshot changelog entry and we hadn't commit the changelog yet, we need to tell gbp buildpackage that the working directory is unclean via the --git-ignore-new option. Once everything looks good, commit the changelog and build a release version:

  gbp dch --release --auto --debian-branch=debian/sid
  git commit -m"Release 1.1-1" debian/changelog
  gbp buildpackage --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid

If you want to share your repository with others, you can use gbp create-remote-repo and gbp pull as usual.

Upstream tarballs and linked upstream history

If you want to track upstream's Git™ but continue to import the upstream tarballs, e.g. to make sure the tarball uploaded to Debian™ has the same checksum as upstream's, you can use the --upstream-vcs-tag option when importing new tarballs with gbp import-orig. Assuming you have the upstream source in your repository with a tag v0.0.1, you can use:

  gbp import-orig --upstream-vcs-tag=v0.0.1 foo_0.0.1.orig.tar.gz

to add upstream's tag as additional parent to the merge commit. See #664771 for more details.

Upstream tarballs and separate upstream history

If you want to have upstream's Git™ history available but don't want to link it to your packaging history you can simply keep it as a separate history. E.g. if you already have a Git™ repository with your packaging, change into that repository and do:

 git remote add upstream https://upstream.example.com/upstream.git
 git fetch upstream

This will pull in upstream's Git™ history into your repo but since your packaging commits and upstreams commits have no common parents the two histories will stay nicely separated. Of course you can browse it and cherry-pick from it but any remote repos you push to will not get upstream's history by default unless you push any of upstream's refs.

Since Git™ has a single tag namespace pushing changes with git push --tags will push upstream's tags (and therefore it's history) too so be sure to only push dedicated tag names.