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
 
 
 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
 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).
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 more output (currently, up to -DDDD is meaningfully different).