Converting to --upstream-vcs-tag

How to convert an existing Debian packaging repository to use --upstream-vcs-tag.

Recently, the Google protobuf developers announced a migration of their project's source code from an svn repository to a git repository. Up until this point, the Debian protobuf package repository had only tracked upstream development by embedding upstream release tarballs using gbp import-orig with pristine-tar. It would be nice to smoothly migrate the packaging repository to additionally make use of the --upstream-vcs-tag option to gbp import-orig, the advantages of which have been well described by Russ Allbery.

This turned out to be harder than expected, so for reference I documented the steps I took below. Note that this packaging repository uses the default gbp import-orig repository layout, where upstream sources are placed on a branch named upstream, and the Debian branch is named master.

Add an upstream remote configured to track the upstream repository's master branch and tags.

$ git remote add --tags --track master upstream https://github.com/google/protobuf.git

The upstream remote shouldn't be confused with our upstream branch. Note that git-remotes are local to the repository, so the upstream remote should probably be documented in the debian/README.source file.

Fetch the upstream branch and tags.

$ git fetch upstream
warning: no common commits
remote: Counting objects: 5210, done.
remote: Compressing objects: 100% (861/861), done.
remote: Total 5210 (delta 3869), reused 5194 (delta 3855)
Receiving objects: 100% (5210/5210), 3.57 MiB | 1.43 MiB/s, done.
Resolving deltas: 100% (3869/3869), done.
From https://github.com/google/protobuf
 * [new branch]      master     -> upstream/master
 * [new tag]         v2.6.0     -> v2.6.0
$

We now have a git-remote upstream, a remote-tracking branch upstream/master which corresponds to the master branch that upstream makes releases from, and a release tag v2.6.0. Note that the remote-tracking branch upstream/master shouldn't be confused with our master branch.

Up until this point, our upstream branch has been synthetically generated by importing upstream's release tarballs with gbp import-orig. We need to merge this synthetic history with upstream/master. Unfortunately, I couldn't find a way to do this without using a temporary branch.

$ git checkout -b tmp upstream/master
Branch tmp set up to track remote branch master from upstream.
Switched to a new branch 'tmp'
$ git merge -s ours -m \
  "Merge the original 'upstream' branch with upstream's new master branch" upstream
Merge made by the 'ours' strategy.
$ git checkout upstream
Switched to branch 'upstream'
Your branch is up-to-date with 'origin/upstream'.
$ git merge --ff-only tmp
Updating 7ed940b..9ba221e
Fast-forward
 CHANGES.txt                                                     |    49 +-
 COPYING.txt => LICENSE                                          |     0
 Makefile.am                                                     |    64 +-
 Makefile.in                                                     |  1041 --
 README.txt => README.md                                         |    49 +-
[...many more lines...]
$ git branch -D tmp
Deleted branch tmp (was 5f18f02).
$

There are now an additional 400 or so commits on our upstream branch, corresponding to the new git repository history published by upstream.

Import the 2.6.0 release tarball against the upstream v2.6.0 tag, using the --upstream-vcs-tag option.

$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
$ gbp import-orig -u 2.6.0 --upstream-vcs-tag=v2.6.0 ~/debian/tarballs/protobuf_2.6.0.orig.tar.gz
gbp:info: Importing '/home/edmonds/debian/tarballs/protobuf_2.6.0.orig.tar.gz' to branch 'upstream'...
gbp:info: Source package is protobuf
gbp:info: Upstream version is 2.6.0
pristine-tar: committed protobuf_2.6.0.orig.tar.gz.delta to branch pristine-tar
gbp:info: Merging to 'master'
gbp:info: Successfully imported version 2.6.0 of /home/edmonds/debian/tarballs/protobuf_2.6.0.orig.tar.gz
$

The upstream branch now contains a mixture of the original series of release tarball content imported by plain gbp import-orig and the upstream/master branch as published by upstream.

Updating the Debian packaging repository when new upstream releases occur only requires a git fetch to pull down upstream's updated git history and release tag and using the --upstream-vcs-tag option when importing the release tarball with gbp import-orig.

Written by on .