|
|
|
|
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
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:
[DEFAULT] 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:
[DEFAULT] 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.
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 upstreamvcs git://git.example.com/libgbp.git cd libgbp git checkout -b debian/latest v1.0
The above makes sure we have debian/latest 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/latest
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/latest --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/latest git commit -m"Release 1.1-1" debian/changelog gbp buildpackage --git-upstream-tag='v%(version)s' --git-debian-branch=debian/latest
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 --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.
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 upstreamvcs https://upstream.example.com/upstream.git git fetch upstreamvcs
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.