documentation: Discuss gdr make-patches vs dgit quilt-fixup, etc.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/dgit.1 b/dgit.1
index 2705d624f419e8f86a7af5f5438653224cb479a2..4cbf10f0dbdc0fc02bb6be7be10d776cbfe2c858 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -185,14 +185,19 @@ archive.
 dgit push always uses the package, suite and version specified in the
 debian/changelog and the .dsc, which must agree.  If the command line
 specifies a suite then that must match too.
+
+With \fB-C\fR, performs a dgit push, additionally ensuring that no
+binary packages are uploaded.
+
+When used on a git-debrebase branch,
+dgit calls git-debrebase
+to prepare the branch
+for source package upload and push.
 .TP
 \fBdgit push-source\fR [\fIsuite\fP]
 Without \fB-C\fR, builds a source package and dgit pushes it.  Saying
 \fBdgit push-source\fR is like saying "update the source code in the
 archive to match my git HEAD, and let the autobuilders do the rest."
-
-With \fB-C\fR, performs a dgit push, additionally ensuring that no
-binary packages are uploaded.
 .TP
 \fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
 Pushes the contents of the specified directory on a remote machine.
@@ -286,6 +291,15 @@ new quilt patch.  dgit cannot convert nontrivial merges, or certain
 other kinds of more exotic history.  If dgit can't find a suitable
 linearisation of your history, by default it will fail, but you can
 ask it to generate a single squashed patch instead.
+
+When used with a git-debrebase branch,
+dgit will ask git-debrebase to prepare patches.
+However,
+dgit can make patches in some situations where git-debrebase fails,
+so dgit quilt-fixup can be useful in its own right.
+To always use dgit's own patch generator
+instead of git-debrebase make-patches,
+pass --git-debrebase=true to dgit.
 .TP
 \fBdgit import-dsc\fR [\fIsub-options\fR] \fI../path/to/.dsc\fR [\fB+\fR|\fB..\fR]branch
 Import a Debian-format source package,

diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod
index f17f1d670e3f5ffb529ecb5fa228f2109bcbab87..6a98ed2d7bbceb1157c2c86a8b3b1e307bc55ba1 100644 (file)
--- a/git-debrebase.1.pod
+++ b/git-debrebase.1.pod
@@ -230,6 +230,9 @@ are not a simple superset of those already in debian/patches,
 make-patches will fail with exit status 7,
 and an error message.
 (The message can be suppress with --quiet-would-amend.)
+If the problem is simply that
+the existing patches were not made by git-debrebase,
+using dgit quilt-fixup instead should succeed.
 
 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]