it might be preferable to
maintain the delta as a rebasing patch series.
For such a workflow see for example
-dgit-maint-gbp(7).
+dgit-maint-debrebase(7) and dgit-maint-gbp(7).
=head1 INITIAL DEBIANISATION
The final command detaches your master branch from the upstream remote,
so that git doesn't try to push anything there, or merge unreleased
upstream commits. If you want to maintain a copy of your packaging
-branch on B<alioth.debian.org> in addition to B<dgit-repos>, you can
+branch on B<salsa.debian.org> in addition to B<dgit-repos>, you can
do something like this:
=over 4
- % git remote add -f origin git.debian.org:/git/collab-maint/foo.git
+ % git remote add -f origin salsa.debian.org:Debian/foo.git
% git push --follow-tags -u origin master
=back
=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
We need a virtual upstream branch with virtual release tags.
[DEFAULT]
upstream-branch = upstream
debian-branch = master
- upstream-tag = %(version)s
+ upstream-tag = upstream/%(version)s
sign-tags = True
pristine-tar = False
[import-orig]
merge-mode = merge
+ merge = False
=back
=over 4
- % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz
+ % gbp import-orig --merge --merge-mode=replace ../foo_1.2.2.orig.tar.xz
=back
-You are now ready to proceed as above, making commits to both the
-upstream source and the I<debian/> directory.
-
-If you want to maintain a copy of your repository on
-B<alioth.debian.org>, you should push both the origin and the upstream
-branches:
+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 git.debian.org:/git/collab-maint/foo.git
+ % 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 both the
+upstream source and the I<debian/> directory.
+
=head1 CONVERTING AN EXISTING PACKAGE
This section explains how to convert an existing Debian package to
=head2 Existing git history using another workflow
-First, dump any existing patch queue:
+First, if you don't already have the git history locally, clone it,
+and obtain the corresponding orig.tar from the archive:
+
+=over 4
+
+ % git clone git.debian.org:collab-maint/foo
+ % cd foo
+ % origtargz
+
+=back
+
+Now dump any existing patch queue:
=over 4
I<debian/source/local-options>. One way to have dgit check your
progress is to run B<dgit build-source>.
-The first dgit push will require I<--overwrite>.
+The first dgit push will require I<--overwrite>. If this is the first
+ever dgit push of the package, consider passing
+I<--deliberately-not-fast-forward> instead of I<--overwrite>. This
+avoids introducing a new origin commit into your git history. (This
+origin commit would represent the most recent non-dgit upload of the
+package, but this should already be represented in your git history.)
=head1 SOURCE PACKAGE CONFIGURATION
=back
-Alternatively, this text could be added to README.source. However,
-this might distract from more important information present in the
-latter file.
+If you are using the version 1.0 source package format, this text
+should be added to README.source instead. The version 1.0 source
+package format ignores debian/source/patch-header.
+
+If you're using the version 3.0 (quilt) source package format, you
+could add this text to README.source instead of
+debian/source/patch-header, but this might distract from more
+important information present in README.source.
=head1 BUILDING AND UPLOADING
-Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit
-push> as detailed in dgit(1). If any command fails, dgit will provide
-a carefully-worded error message explaining what you should do. If
-it's not clear, file a bug against dgit. Remember to pass I<--new>
-for the first upload.
+Use B<dgit build>, B<dgit sbuild>, B<dgit pbuilder>, B<dgit
+cowbuilder>, B<dgit push-source>, and B<dgit push> as detailed in
+dgit(1). If any command fails, dgit will provide a carefully-worded
+error message explaining what you should do. If it's not clear, file
+a bug against dgit. Remember to pass I<--new> for the first upload.
-As an alternative to B<dgit build> and friends, you can use a tool
-like gitpkg(1). This works because like dgit, gitpkg(1) enforces that
-HEAD has exactly the contents of the source package. gitpkg(1) is
-highly configurable, and one dgit user reports using it to produce and
-test multiple source packages, from different branches corresponding
-to each of the current Debian suites.
+If you want to upload with git-debpush(1), for the first upload you
+should pass the B<--quilt=smash> quilt mode option (see
+git-debpush(1)).
+
+As another alternative to B<dgit build> and friends, you can use a
+tool like gitpkg(1). This works because like dgit, gitpkg(1) enforces
+that HEAD has exactly the contents of the source package. gitpkg(1)
+is highly configurable, and one dgit user reports using it to produce
+and test multiple source packages, from different branches
+corresponding to each of the current Debian suites.
If you want to skip dgit's checks while iterating on a problem with
the package build (for example, you don't want to commit your changes
=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
-tarballs", above.
+tarballs", above. You will also need your upstream branch. Above, we
+pushed this to B<salsa.debian.org>. You will need to clone or fetch
+from there, instead of relying on B<dgit clone>/B<dgit fetch> alone.
Then, either
=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
+In the following, replace I<1.2.3> with I<upstream/1.2.3>.
+
=head2 Reviewing & merging the release
It's a good idea to preview the merge of the new upstream release.
=over 4
- % git diff --stat master..1.2.3 -- . ':!debian'
+ % git diff --name-status --diff-filter=ADR master..1.2.3 -- . ':!debian'
=back
~ianmdlvl / dgit.git / blobdiff