dgit-maint-debrebase(7): it's an example

[dgit.git] / dgit-maint-debrebase.7.pod

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index f46944fe53cb646ef3b68a059e0f1ea23884b5f5..cd470ce144f077a273317a4b16872baace00cc4f 100644 (file)
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -55,8 +55,9 @@ 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 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
 
@@ -270,6 +271,25 @@ 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 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
 
@@ -485,9 +505,24 @@ option detailed in gbp-import-orig(1).
 
 =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
 
@@ -498,6 +533,13 @@ 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 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
 
 dgit(1), dgit(7)