dgit-maint-debrebase(7): improve advice about minimising stitches

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

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index a2ae3f8911cd0a8544fd820f74f6956a91db3de0..601b8e92bd6a963c3e786552ec8c8cd3227802d1 100644 (file)
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -400,8 +400,8 @@ git remote such as B<salsa.debian.org>,
 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 upload in a single debrebase, so that there is a
-single debrebase stitch.
+needed for this editing session in a single debrebase, so that there
+is a single debrebase stitch.
 
 =head1 BUILDING AND UPLOADING
 
@@ -488,8 +488,8 @@ 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 delta queue.
+your patches.  A debrebase can be used to strip both the patch and the
+reversion from the delta queue.
 
 =head2 Manually applying the debdiff
 
@@ -505,12 +505,15 @@ I<--overwrite>.
 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 convention you can use to minimise the number of pseudomerges is to
-debrebase only right before you upload.
+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>.
 
-Before that point, instead of editing the existing delta queue, you
+It is possible to reduce the number of pseudomerges further by
+derebasing 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 freely push and pull
+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.