chiark / gitweb /
dgit.1: Document --quilt=gbp et al.
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 9 Oct 2016 00:33:31 +0000 (01:33 +0100)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Mon, 10 Oct 2016 00:01:10 +0000 (01:01 +0100)
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
TODO.BRANCH
dgit.1

index 34ea6ce..88633e5 100644 (file)
@@ -1,8 +1,4 @@
 
-OTHER
-
- * Document --quilt=unapplied|gbp|dpm
-
 
 CHECK BTS
 
diff --git a/dgit.1 b/dgit.1
index 0659562..b3a4f93 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).