=item
-Manipulate the patch queue using the full power of git-rebase(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).
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 examples, see "BEHAVIOUR TO AVOID" below). For such
-packages, consider the workflow described in dgit-maint-merge(7).
+complexity -- for example, you cannot use B<git merge> to incorporate
+changes from other contributors. For such packages, consider the
+workflow described in dgit-maint-merge(7).
=head1 INITIAL DEBIANISATION
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.
+to patch the upstream source, see "EDITING THE DELTA 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).
+work with upstream tags rather than any branches, except temporary
+branches used to prepare patches for forwarding upstream, for example.
Finally, you need an orig tarball:
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 GIT CONFIGURATION
+
+This workflow does not 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 repository 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
=back
-=head1 EDITING THE PATCH QUEUE
+=head1 EDITING THE DELTA QUEUE
=head2 Adding new patches
=back
If you take this approach, you should be very careful not to start the
-rebase earlier than the beginning of the patch queue.
+rebase earlier than the beginning of the delta queue.
=head2 Editing patches: finishing a debrebase
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
+all of the editing of the delta 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
+point, 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 freely push and pull from
B<salsa.debian.org> during this. Just before uploading, you debrebase
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
+=head2 Laundering the delta 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
+have git-debrebase(1) shuffle your branch such that the Debian delta
queue appears at the end:
=over 4
=head1 INCORPORATING NMUS
+In the simplest case,
+
=over 4
- % dgit pull
+ % 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.
+
+=head2 Rebasing your work onto the NMU
+
+=over 4
+
+ % git rebase dgit/dgit/sid
=back
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.
+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 SEE ALSO
~ianmdlvl / dgit.git / blobdiff