From 9c83425fc20526e6bb7a50ce5a467fa8fa0c7600 Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 9 Oct 2016 15:21:20 +0100
Subject: [PATCH] dgit.1: Discourage use of the --PROGRAM:OPTION escape hatch.

(Apropos of various bug reports including #800060.)

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---
 debian/changelog |  2 ++
 dgit.1           | 80 ++++++++++++++++++++++++++----------------------
 2 files changed, 46 insertions(+), 36 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index e128e1e7..83c602c1 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -53,6 +53,8 @@ dgit (1.5~~) unstable; urgency=medium
   Documentation:
   * Document the dgit-distro.DISTRO.quilt-mode config setting.
   * Clarify the --clean= options' documentation.  Closes:#800054.
+  * Discourage use of the --PROGRAM:OPTION escape hatch.  (Apropos
+    of various bug reports including #800060.)
 
   Bugfixes:
   * When cleaning up after failed clone, stat the to-be-cleaned-up
diff --git a/dgit.1 b/dgit.1
index a0159060..437a5740 100644
--- a/dgit.1
+++ b/dgit.1
@@ -507,6 +507,50 @@ Passed to dpkg-genchanges (eventually).
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP
+.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
+Specifies a single additional option to pass to
+.BR curl ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.BR sbuild ,
+.BR ssh ,
+.BR dgit ,
+.BR gbp-pq ,
+.BR gbp-build ,
+or
+.BR mergechanges .
+Can be repeated as necessary.
+
+Use of this ability should not normally be necessary.
+It is provided for working around bugs,
+or other unusual situations.
+If you use these options,
+you may violate dgit's assumptions
+about the behaviour of its subprograms
+and cause lossage.
+
+For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
+the option applies only when the program is invoked directly by dgit.
+Usually, for passing options to dpkg-genchanges, you should use
+.BR --ch: \fIoption\fR.
+
+Specifying --git is not effective for some lower-level read-only git
+operations performed by dgit, and also not when git is invoked by
+another program run by dgit.
+
+See notes above regarding ssh and dgit.
+
+NB that --gpg:option is not supported (because debsign does not
+have that facility).
+But see
+.B -k
+and the
+.B keyid
+distro config setting.
+.TP
 .RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
 Specifies alternative programs to use instead of
 .BR curl ,
@@ -568,42 +612,6 @@ git to access dgit-repos, only git's idea of what ssh to use (eg,
 .BR GIT_SSH )
 is relevant.
 .TP
-.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
-Specifies a single additional option to pass to
-.BR curl ,
-.BR dput ,
-.BR debsign ,
-.BR dpkg-source ,
-.BR dpkg-buildpackage ,
-.BR dpkg-genchanges ,
-.BR sbuild ,
-.BR ssh ,
-.BR dgit ,
-.BR gbp-pq ,
-.BR gbp-build ,
-or
-.BR mergechanges .
-Can be repeated as necessary.
-
-For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
-this applies only when the program is invoked directly by dgit.
-Usually, for passing options to dpkg-genchanges, you should use
-.BR --ch: \fIoption\fR.
-
-Specifying --git not effective for some lower-level read-only git
-operations performed by dgit, and also not when git is invoked by
-another program run by dgit.
-
-See notes above regarding ssh and dgit.
-
-NB that --gpg:option is not supported (because debsign does not
-have that facility).
-But see
-.B -k
-and the
-.B keyid
-distro config setting.
-.TP
 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
 Specifies that the suite to be operated on is part of distro
 .IR distro .
-- 
2.30.2