dgit.1: Document --quilt=gbp et al.

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

diff --git a/TODO.BRANCH b/TODO.BRANCH
index 34ea6ce84f8642f1def536cb65c4ec641475af69..88633e51c810c815c72e562ffce3347d3a617c58 100644 (file)
--- a/TODO.BRANCH
+++ b/TODO.BRANCH
@@ -1,8 +1,4 @@
 
-OTHER
-
- * Document --quilt=unapplied|gbp|dpm
-
 
 CHECK BTS
 

diff --git a/dgit.1 b/dgit.1
index 0659562796a5e66b754a63a520ac6b0d58969825..b3a4f9392be39fac79845503c5295aa5eda7c4d7 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -419,6 +419,54 @@ Do not check whether up source format `3.0 (quilt)' metadata needs
 fixing up.  If you use this option and the metadata did in fact need
 fixing up, dgit push will fail.
 .TP
+.BR --quilt=gbp " | " --quilt=dpm " | " --quilt=unapplied
+Tell dgit that you are using a nearly-dgit-compatible git branch,
+aka a
+.BR "maintainer view" ,
+and
+do not want your branch changed by dgit.
+
+.B --quilt=gbp
+is for use with git-buildpackage.
+Your HEAD is expected to be
+a patches-unapplied git branch, except that it might contain changes
+to upstream .gitignore files.
+
+.B --quilt=dpm
+is for use with git-dpm.
+Your HEAD is expected to be
+a patches-applied git branch,
+except that it might contain changes to upstream .gitignore files.
+
+.B --quilt=unapplied
+specifies that your HEAD is a patches-unapplied git branch (and
+that any changes to upstream .gitignore files are represented as
+patches in debian/patches).
+
+Instead, dgit quilt-fixup and dgit-push will automatically
+convert your git branch into the right form,
+and dgit push will push the
+dgit-compatible form (the
+.BR "dgit view" )
+to the dgit git server.
+The dgit view will be visible to you
+in the dgit remote tracking branches, but your own branch will
+not be modified.
+dgit will create a tag
+.BI debian/ version
+for the maintainer view, and the dgit tag
+.BI archive/debian/ version
+for the dgit view.
+
+.B If you have a branch like this it is essential to specify the appropriate --quilt= option!
+This is because it is not always possible to tell: a patches-unapplied
+git branch of a package with one patch, for example, looks just the
+same as a patches-applied branch where the user has used git revert to
+undo the patch, expecting to actually revert it.
+If you fail to specify the right \-\-quilt option,
+and you aren't too lucky, dgit will notice the problem and stop,
+with a useful hint. 
+.TP
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 more output (currently, up to -DDDD is meaningfully different).