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.
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
--git-upstream-tag command line option
upstream-tag configuration file
variable to specify upstream's tag format.
For example a common upstream format is to put
v in front of the version
number. In this case, the configuration option would look
[DEFAULT] upstream-tag = v%(version)s
version will be replaced by gbp
with the upstream version number as determined from
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
Some upstreams use other formats though and don't separate
numbers by dots but rather by
-) or anything else. In
order to cope with that you can use version mangling of these
characters via substitution. The substitution works as
[DEFAULT] upstream-tag = v%(version%.%_)s
This means that each occurrence
. will be replaced
_ in the upstream version
number. For example the upstream
1.2.3 as determined from
debian/changelog will be looked up
as Git™ tag
If you want the substitution to be the
you have to escape it. E.g.
%(version%-%\%)s will replace
Only a single replacement is supported and it can only replace a single character.
Since some of the possible mangling characters
% 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
--git-pristine-tar-commit option or you
can use gbp pristine-tar after you've created the
This will make sure others building your package can exactly
regenerate the tarball you created when building the
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
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
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
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
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
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
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.
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
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.
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.