=back
+=head3 Using untagged upstream commits
+
+=over 4
+
+Sometimes upstream does not tag their releases, or you want to package
+an unreleased git snapshot. In such a case you can create your own
+upstream release tag, of the form B<upstream/>I<ver>, where I<ver> is
+the upstream version you plan to put in I<debian/changelog>. The
+B<upstream/> prefix ensures that your tag will not clash with any tags
+upstream later creates.
+
+For example, suppose that the latest upstream release is 1.2.2 and you
+want to package git commit ab34c21 which was made on 2013-12-11. A
+common convention is to use the upstream version number
+1.2.2+git20131211.ab34c21 and so you could use
+
+=over 4
+
+ % git tag -s upstream/1.2.2+git20131211.ab34c21 ab34c21
+
+=back
+
+to obtain a release tag, and then proceed as above.
+
+=back
+
=head2 When upstream releases only tarballs
Because we want to work in git, we need a virtual upstream branch with
% mkdir foo
% cd foo
% git init
+ % git checkout -b upstream
+ % gbp import-orig \
+ --upstream-branch=upstream --debian-branch=master \
+ --upstream-tag='upstream/%(version)s' \
+ --sign-tags --no-pristine-tar \
+ ../foo_1.2.2.orig.tar.xz
+ % git branch -f upstream
=back
-Now create I<debian/gbp.conf>:
+This should leave you on the master branch. Next, our upstream branch
+cannot be pushed to B<dgit-repos>, but since we will need it whenever
+we import a new upstream version, we must push it somewhere. The
+usual choice is B<salsa.debian.org>:
+
+=over 4
+
+ % git remote add -f origin salsa.debian.org:Debian/foo.git
+ % git push --follow-tags -u origin master upstream
+
+=back
+
+You are now ready to proceed as above, making commits to the
+I<debian/> directory and to the upstream source. As above, for
+technical reasons, B<it is essential that your first commit introduces
+the debian/ directory containing at least one file, and does nothing
+else.> In other words, make a commit introducing I<debian/> before
+patching the upstream source.
+
+A convenient way to ensure this requirement is satisfied is to start
+by creating I<debian/gbp.conf>:
=over 4
[DEFAULT]
upstream-branch = upstream
debian-branch = master
- upstream-tag = %(version)s
+ upstream-tag = upstream/%(version)s
sign-tags = True
pristine-tar = False
pristine-tar-commit = False
[import-orig]
- merge-mode = merge
+ merge = False
=back
-gbp-import-orig(1) requires a pre-existing upstream branch:
+and commit that:
=over 4
% git add debian/gbp.conf && git commit -m "create gbp.conf"
- % git checkout --orphan upstream
- % git rm -rf .
- % git commit --allow-empty -m "initial, empty branch for upstream source"
- % git checkout -f master
=back
-Then we can import the upstream version:
-
-=over 4
-
- % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz
-
-=back
-
-Our upstream branch cannot be pushed to B<dgit-repos>, but since we
-will need it whenever we import a new upstream version, we must push
-it somewhere. The usual choice is B<salsa.debian.org>:
-
-=over 4
-
- % git remote add -f origin salsa.debian.org:Debian/foo.git
- % git push --follow-tags -u origin master upstream
-
-=back
-
-You are now ready to proceed as above, making commits to the
-I<debian/> directory and to the upstream source. As above, for
-technical reasons, B<it is essential that your first commit introduces
-the debian/ directory containing at least one file, and does nothing
-else.> In other words, make a commit introducing I<debian/> before
-patching the upstream source.
+Note that we couldn't create I<debian/gbp.conf> before now for the
+same technical reasons which require our first commit to introduce
+I<debian/> without patching the upstream source. That's why we had to
+pass a lot of options to our first call to gbp-import-orig(1).
=head1 CONVERTING AN EXISTING PACKAGE
=over 4
- % git remote update
+ % git fetch --tags upstream
=back
+If you want to package an untagged upstream commit (because upstream
+does not tag releases or because you want to package an upstream
+development snapshot), see "Using untagged upstream commits" above.
+
=head3 When upstream releases only tarballs
You will need the I<debian/gbp.conf> from "When upstream releases only
=over 4
- % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz
+ % gbp import-orig ../foo_1.2.3.orig.tar.xz
=back
=over 4
- % gbp import-orig --no-merge --uscan
+ % gbp import-orig --uscan
=back
=back
+replacing I<1.2.3> with I<upstream/1.2.3> if you imported a tarball.
+
This invocation of git-debrebase(1) involves a git rebase. You may
need to resolve conflicts if the Debian delta queue does not apply
cleanly to the new upstream source.
=back
-Additionally pass I<--name-status> and I<--diff-filter=ADR> to see
+Also, diff with I<--name-status> and I<--diff-filter=ADR> to see
just the list of added or removed files, which is useful to determine
whether there are any new or deleted files that may need accounting
for in your copyright file.
~ianmdlvl / dgit.git / blobdiff