non-native Debian package using B<dgit>. We maintain the Debian delta
as a series of git commits on our master branch. We use
git-debrebase(1) to shuffle our branch such that this series of git
-commits appears at the end of the branch. This does not involve
-rewriting any public git history.
+commits appears at the end of the branch. All the public git history
+is fast-forwarding, i.e., we do not rewrite and force-push.
Some advantages of this workflow:
=item
-Manipulate the patch queue using the full power of git-rebase(1),
-instead of relying on quilt(1), and without having to switch away to
-another branch, as with gbp-pq(1).
+Manipulate the delta queue using the full power of git-rebase(1),
+instead of relying on quilt(1), and without having to switch back and
+forth between patches-applied and patches-unapplied branches when
+committing changes and trying to build, as with gbp-pq(1).
+
+=item
+
+If you are using 3.0 (quilt), provide your delta queue as a properly
+separated series of quilt patches in the source package that you
+upload to the archive (unlike with dgit-maint-merge(7)).
=item
where it can benefit downstream dgit users, such as people using dgit
to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)).
+=item
+
+Minimise the amount you need to know about 3.0 (quilt) in order to
+maintain Debian source packages which use that format.
+
=back
This workflow is appropriate for packages where the Debian delta
contains multiple pieces which interact, or which you don't expect to
be able to upstream soon. For packages with simple and/or short-lived
-Debian deltas, use of git-debrebase(1) might introduce unneeded
-complexity. For such packages, consider the workflow described in
+Debian deltas, use of git-debrebase(1) introduces unneeded complexity.
+For such packages, consider the workflow described in
dgit-maint-merge(7).
=head1 INITIAL DEBIANISATION
-=head2 When upstream tags releases in git
-
This section explains how to start using this workflow with a new
package. It should be skipped when converting an existing package to
this workflow.
+=head2 When upstream tags releases in git
+
Suppose that the latest stable upstream release is 1.2.2, and this has
been tagged '1.2.2' by upstream.
=back
-Now go ahead and Debianise your package. Just make commits on the
-master branch, adding things in the I<debian/> directory. If you need
-to patch the upstream source, see "EDITING THE PATCH QUEUE", below.
-Note that there is no need to maintain a separate 'upstream' branch,
-unless you also happen to be involved in upstream development. We
-work with upstream tags rather than any branches, except when
-forwarding patches (see FORWARDING PATCHES UPSTREAM, below).
+Now go ahead and Debianise your package. Make commits on the master
+branch, adding things in the I<debian/> directory, or patching the
+upstream source. 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.
Finally, you need an orig tarball:
This tarball is ephemeral and easily regenerated, so we don't commit
it anywhere (e.g. with tools like pristine-tar(1)).
-=head3 Verifying upstream's tarball releases
+=head3 Comparing upstream's tarball releases
=over 4
-It can be a good idea to compare upstream's released tarballs with the
-release tags, at least for the first upload of the package. If they
-are different, you might need to add some additional steps to your
-I<debian/rules>, such as running autotools.
+The above assumes that you know how to build the package from git and
+that doing so is straightforward.
+
+If, as a user of the upstream source, you usually build from upstream
+tarball releases, rather than upstream git tags, you will sometimes
+find that the git tree doesn't contain everything that is in the
+tarball.
+
+Additional build steps may be needed. For example, you may need your
+I<debian/rules> to run autotools.
-A convenient way to perform this check is to import the tarball as
-described in the following section, using a different value for
-'upstream-tag', and then use git-diff(1) to compare the imported
-tarball to the release tag. If they are the same, you can use
-upstream's tarball instead of running git-deborig(1).
+You can compare the upstream tarball release, and upstream git tag,
+within git, by importing the tarball into git as described in the
+next section, using a different value for 'upstream-tag', and then
+using git-diff(1) to compare the imported tarball to the release tag.
=back
=head2 When upstream releases only tarballs
-We need a virtual upstream branch with virtual release tags.
-gbp-import-orig(1) can manage this for us. To begin
+Because we want to work in git, we need a virtual upstream branch with
+virtual release tags. gbp-import-orig(1) can manage this for us. To
+begin
=over 4
=back
You are now ready to proceed as above, making commits to the
-I<debian/> directory.
+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.
=head1 CONVERTING AN EXISTING PACKAGE
=back
-If your tree is patches-unapplied, you will need to make a commit
-corresponding to each of the quilt patches. gbp-pq(1) can do this for
-us:
+If your tree is patches-unapplied, some conversion work is needed.
+You can use
=over 4
- % gbp pq import
- % gbp pq switch
- % git merge --ff-only patch-queue/master
- % gbp pq drop
+ git debrebase convert-from-gbp
=back
=back
-=for dgit-test dpkg-source-ignores begin
-
Now you simply need to ensure that your git HEAD is dgit-compatible,
-i.e., it is exactly what you would get if you ran
-B<dpkg-buildpackage -i'(?:^|/)\.git(?:/|$)' -I.git -S>
-and then unpacked the resultant source package.
-
-=for dgit-test dpkg-source-ignores end
+i.e., it is exactly what you would get if you deleted .git, invoked
+B<dpkg-buildpackage -S>, and then unpacked the resultant source
+package.
To achieve this, you might need to delete
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>. 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.)
+The first dgit push will require I<--overwrite>.
+
+=head1 GIT CONFIGURATION
+
+git-debrebase(1) does not yet support using B<git merge> to merge
+divergent branches of development (see "OTHER MERGES" in
+git-debrebase(5)). You should configure git such that B<git pull>
+does not try to merge:
+
+=over 4
+
+ % git config --local pull.rebase true
+
+=back
+
+Now when you pull work from other Debian contributors, git will rebase
+your work on top of theirs.
+
+If you use this clone for upstream development in addition to
+Debian packaging work, you may not want to set this global setting.
+Instead, see the B<branch.autoSetupRebase> and
+B<branch.E<lt>nameE<gt>.rebase> settings in git-config(5).
=head1 IMPORTING NEW UPSTREAM RELEASES
+There are two steps: obtaining git refs that correspond to the new
+release, and importing that release using git-debrebase(1).
+
=head2 Obtaining the release
=head3 When upstream tags releases in git
=over 4
- % git debrebase new-upstream-v0 1.2.3
- % dch -v1.2.3-1 New upstream release.
- % git add debian/changelog && git commit -m changelog
+ % git debrebase new-upstream 1.2.3
=back
-You can now review the merge of the new upstream release:
+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.
+
+If all went well, you can now review the merge of the new upstream
+release:
=over 4
=back
-=head1 EDITING THE PATCH QUEUE
+=head1 EDITING THE DEBIAN PACKAGING
+
+Just make commits on master that change the contents of I<debian/>.
+
+=head1 EDITING THE DELTA QUEUE
=head2 Adding new patches
Adding new patches is straightforward: just make commits touching only
files outside of the I<debian/> directory. You can also use tools
-like git-revert(1), git-am(1) and git-cherrypick(1).
+like git-revert(1), git-am(1) and git-cherry-pick(1).
=head2 Editing patches: starting a debrebase
=over 4
- % git debrebase
+ % git debrebase -i
=back
to start an interactive rebase. You can edit, re-order and delete
-commits just as you would during B<git rebase -i>. Alternatively, you
-can perform a non-interactive rebase like this:
-
-=over 4
-
- % git debrebase -- [git-rebase options...]
-
-=back
-
-For example,
-
-=over 4
-
- % git debrebase -- --autosquash
-
-=back
-
-A third alternative is to have git-debrebase(1) shuffle all the Debian
-changes to the end of your branch, and then manipulate them yourself
-using git-rebase(1). For example,
-
-=over 4
-
- % git debrebase launder
- % git rebase -i HEAD^5 # there are 4 Debian patches
-
-=back
+commits just as you would during B<git rebase -i>.
=head2 Editing patches: finishing a debrebase
=over 4
- % git debrebase stitch
+ % git debrebase conclude
=back
-Note that each time you stitch a debrebase you introduce a pseudomerge
-into your git history, which may make it harder to read. Try to do
-all of the editing of the patch queue that you think will be needed
-for this upload in a single debrebase, so that there is a single
-debrebase stitch.
-
-A strategy is to debrebase only right before you upload. Before that
-point, instead of editing the existing patch series, you append fixup
-commits (and reversions of commits) that alter the upstream source to
-the required state. You can freely push and pull from
-B<salsa.debian.org> during this. Just before uploading, you debrebase
-to tidy everything up.
+Note that each time you conclude a debrebase you introduce a
+pseudomerge into your git history, which may make it harder to read.
+Try to do all of the editing of the delta queue that you think will be
+needed for this editing session in a single debrebase, so that there
+is a single debrebase stitch.
=head1 BUILDING AND UPLOADING
-Use B<dgit build>, B<dgit sbuild>, B<dgit push> and B<dgit
-push-source> 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.
-
-After dgit pushing, be sure to git push to B<salsa.debian.org>, if
-you're using that.
+You can use dpkg-buildpackage(1) for test builds. When you are ready
+to build for an upload, use B<dgit sbuild>, B<dgit pbuilder> or B<dgit
+cowbuilder>.
-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.
+Upload with B<dgit push> or B<dgit push-source>. Remember to pass
+I<--new> if the package is new in the target suite.
-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
-to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
-
-=head2 Laundering the patch queue before uploading
-
-Just before you B<dgit push> or B<dgit push-source>, you might want to
-have git-debrebase(1) shuffle your branch such that the Debian patch
-queue appears at the end:
+Right before uploading, if you did not just already do so, you might
+want to have git-debrebase(1) shuffle your branch such that the Debian
+delta queue appears right at the tip of the branch you will push:
=over 4
- % git debrebase launder
+ % git debrebase
% dgit push-source
=back
Note that this will introduce a new pseudomerge.
+After dgit pushing, be sure to git push to B<salsa.debian.org>, if
+you're using that.
+
=head1 HANDLING DFSG-NON-FREE MATERIAL
-=head2 When upstream tags releases in git
+=head2 Illegal material
-We create a DFSG-clean tag to import to master:
+Here we explain how to handle material that is merely DFSG-non-free.
+Material which is legally dangerous (for example, files which are
+actually illegal) cannot be handled this way.
+
+If you encounter possibly-legally-dangerous material in the upstream
+source code you should seek advice. It is often best not to make a
+fuss on a public mailing list (at least, not at first). Instead,
+email your archive administrators. For Debian that is
+ To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org
+
+=head2 DFSG-non-free: When upstream tags releases in git
+
+Our approach is to maintain a DFSG-clean upstream branch, and create
+tags on this branch for each release that we want to import. We then
+import those tags per "Importing the release", above.
+
+For the first upstream release that requires DFSG filtering:
=over 4
- % git checkout -b pre-dfsg 1.2.3
+ % git checkout -b upstream-dfsg 1.2.3
% git rm evil.bin
% git commit -m "upstream version 1.2.3 DFSG-cleaned"
% git tag -s 1.2.3+dfsg
% git checkout master
- % git branch -D pre-dfsg
+ % # proceed with "Importing the release" on 1.2.3+dfsg tag
=back
-Before invoking B<git debrebase new-upstream-v0>, you should first
-determine whether it would be legally dangerous for the non-free
-material to be publicly accessible in the git history on
-B<dgit-repos>.
+And for subsequent releases (whether or not they require filtering):
-If it would be dangerous, there is a big problem;
-in this case please consult your archive administrators
-(for Debian this is the dgit administrator dgit-owner@debian.org
-and the ftpmasters ftpmaster@ftp-master.debian.org).
+=over 4
-=head2 When upstream releases only tarballs
+ % git checkout upstream-dfsg
+ % git merge 1.2.4
+ % git rm further-evil.bin # if needed
+ % git commit -m "upstream version 1.2.4 DFSG-cleaned" # if needed
+ % git tag -s 1.2.4+dfsg
+ % git checkout master
+ % # proceed with "Importing the release" on 1.2.4+dfsg tag
+
+=back
+
+Our upstream-dfsg 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. Assuming that you have already set up an origin
+remote per the above,
+
+=over 4
+
+ % git push --follow-tags -u origin master upstream-dfsg
+
+=back
+
+=head2 DFSG-non-free: When upstream releases only tarballs
The easiest way to handle this is to add a B<Files-Excluded> field to
I<debian/copyright>, and a B<uversionmangle> setting in
I<debian/watch>. See uscan(1). Alternatively, see the I<--filter>
option detailed in gbp-import-orig(1).
-=head1 FORWARDING PATCHES UPSTREAM
+=head1 INCORPORATING NMUS
-The basic steps are:
+In the simplest case,
=over 4
-=item 1.
+ % dgit fetch
+ % git merge --ff-only dgit/dgit/sid
+
+=back
+
+If that fails, because your branch and the NMUers work represent
+divergent branches of development, you have a number of options. Here
+we describe the two simplest.
+
+Note that you should not try to resolve the divergent branches by
+editing files in I<debian/patches>. Changes there would either cause
+trouble, or be overwritten by git-debrebase(1).
+
+=head2 Rebasing your work onto the NMU
+
+=over 4
+
+ % git rebase dgit/dgit/sid
+
+=back
+
+If the NMUer added new commits modifying the upstream source, you will
+probably want to debrebase before your next upload to tidy those up.
+
+For example, the NMUer might have used git-revert(1) to unapply one of
+your patches. A debrebase can be used to strip both the patch and the
+reversion from the delta queue.
+
+=head2 Manually applying the debdiff
+
+If you cannot rebase because you have already pushed to
+B<salsa.debian.org>, say, you can manually apply the NMU debdiff,
+commit and debrebase. The next B<dgit push> will require
+I<--overwrite>.
+
+=head1 HINTS AND TIPS
+
+=head2 Minimising pseudomerges
+
+Above we noted that each time you conclude a debrebase, you introduce
+a pseudomerge into your git history, which may make it harder to read.
+
+A simple convention you can use to minimise the number of pseudomerges
+is to B<git debrebase conclude> only right before you upload or push
+to B<salsa.debian.org>.
+
+It is possible, though much less convenient, to reduce the number of
+pseudomerges yet further. We debrebase only (i) when importing a new
+release, and (ii) right before uploading. Instead of editing the
+existing delta queue, you append fixup commits (and reversions of
+commits) that alter the upstream source to the required state. You
+can push and pull to and from B<salsa.debian.org> during this. Just
+before uploading, you debrebase, once, to tidy everything up.
-Create a new branch based off upstream's master branch.
+=head2 The debian/patches directory
-=item 2.
+In this workflow, I<debian/patches> is purely an output of
+git-debrebase(1). You should not make changes there. They will
+either cause trouble, or be ignored and overwritten by
+git-debrebase(1).
-git-cherry-pick(1) commits from your master branch onto your new
-branch.
+I<debian/patches> will often be out-of-date because git-debrebase(1)
+will only regenerate it when it needs to. So you should not rely on
+the information in that directory. When preparing patches to forward
+upstream, you should use git-format-patch(1) on git commits, rather
+than sending files from I<debian/patches>.
-=item 3.
+=head2 Upstream branches
-Push the branch somewhere and ask upstream to merge it, or use
-git-format-patch(1) or git-request-pull(1).
+In this workflow, we specify upstream tags rather than any branches.
+
+Except when (i) upstream releases only tarballs, (ii) we require DFSG
+filtering, or (iii) you also happen to be involved in upstream
+development, we do not maintain any local branch corresponding to
+upstream, except temporary branches used to prepare patches for
+forwarding, and the like.
+
+The idea here is that from Debian's point of view, upstream releases
+are immutable points in history. We want to make sure that we are
+basing our Debian package on a properly identified upstream version,
+rather than some arbitrary commit on some branch. Tags are more
+useful for this.
+
+Upstream's branches remain available as the git remote tracking
+branches for your upstream remote, e.g. I<remotes/upstream/master>.
+
+=head2 The first ever dgit push
+
+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.)
+
+=head2 Alternative ways to start a debrebase
+
+Above we started an interactive debrebase by invoking git-debrebase(1)
+like this:
+
+=over 4
+
+ % git debrebase -i
=back
-For example (and it is only an example):
+It is also possible to perform a non-interactive rebase, like this:
=over 4
- % # fork foo.git on GitHub
- % git remote add -f fork git@github.com:spwhitton/foo.git
- % git checkout -b fix-error upstream/master
- % git config branch.fix-error.pushRemote fork
- % git cherry-pick master^2
- % git push
- % # submit pull request on GitHub
+ % git debrebase -- [git-rebase options...]
=back
-Note that when you merge an upstream release containing your forwarded
-patches, a debrebase will transparently handle "dropping" the patches
-that have been forwarded, "retaining" the ones that haven't.
-=head1 INCORPORATING NMUS
+A third alternative is to have git-debrebase(1) shuffle all the Debian
+changes to the end of your branch, and then manipulate them yourself
+using git-rebase(1) directly. For example,
=over 4
- % dgit pull
+ % git debrebase
+ % git rebase -i HEAD~5 # there are 4 Debian patches
=back
-If the NMUer added new commits modifying the upstream source, you will
-probably want to debrebase before your next upload to tidy those up.
-
-For example, the NMUer might have used git-revert(1) to unapply one of
-your patches. A debrebase will strip both the patch and the reversion
-from the patch series.
+If you take this approach, you should be very careful not to start the
+rebase too early,
+including before the most recent pseudomerge.
+git-rebase without a base argument will often
+start the rebase too early,
+and should be avoided.
+Run git-debrebase instead.
=head1 SEE ALSO
-dgit(1), dgit(7)
+dgit(1), dgit(7), git-debrebase(1), git-debrebase(5)
=head1 AUTHOR
~ianmdlvl / dgit.git / blobdiff