chiark / gitweb /
Better documentation for quilt series handling.
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 23 Nov 2014 13:51:22 +0000 (13:51 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 23 Nov 2014 13:51:22 +0000 (13:51 +0000)
debian/changelog
dgit.1

index 6629b0b..ecd2420 100644 (file)
@@ -35,6 +35,8 @@ dgit (0.23~) unstable; urgency=low
     al.  Client users probably don't want this stuff.  Also, it provides a
     convenient way to publish the dependencies.
 
+  * Better documentation for quilt series handling.
+
  --
 
 dgit (0.22.1) unstable; urgency=high
diff --git a/dgit.1 b/dgit.1
index 1676bb8..b027db7 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -190,6 +190,12 @@ patches in debian/patches and also commit the resulting changes to
 git.
 
 This is normally done automatically by dgit build and dgit push.
+
+dgit will try to turn each relevant commit in your git history into a
+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.
 .TP
 .B dgit version
 Prints version information and exits.
@@ -246,11 +252,35 @@ This can be useful with build, if you plan to commit later.  (dgit
 push will still ensure that the .dsc you upload and the git tree
 you push are identical, so this option won't make broken pushes.)
 .TP
-.BR --no-quilt-fixup
-Do not fix up source format `3.0 (quilt)' metadata.  If you use this
-option and the package did in fact need fixing up, dgit push will
+.BR --quilt=linear
+When fixing up source format `3.0 (quilt)' metadata, insist on
+generating a linear patch stack.  If such a stack cannot be generated,
 fail.
 .TP
+.BR --quilt=auto
+When fixing up source format `3.0 (quilt)' metadata, prefer to
+generate a linear patch stack, but if that doesn't seem possible,
+generate a single squashed patch for all the changes made in git.
+This is not a good idea for an NMU in Debian.
+.TP
+.BR --quilt=smash
+When fixing up source format `3.0 (quilt)' metadata,
+generate a single squashed patch for all the changes made in git.
+This is not a good idea for an NMU in Debian.
+.TP
+.BR --quilt=nofix
+Check whether source format `3.0 (quilt)' metadata would need fixing
+up, but, if it does, fail.  You must then fix the metadata yourself
+somehow before pushing.  (NB that dpkg-source --commit will not work
+because the dgit git tree does not have a
+.B .pc
+directory.)
+.TP
+.BR --no-quilt-fixup
+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
 .BI -D
 Prints debugging information to stderr.  Repeating the option produces
 more output (currently, up to -DD is meaningfully different).
@@ -419,6 +449,11 @@ descendant of the state of the archive, as provided by dgit in the
 remote tracking branch
 .BR remotes/dgit/dgit/ \fIsuite\fR.
 
+If you are using dgit to do an NMU, and don't know about the
+maintainers' preferred packaging workflows, you should make your
+changes as a linear series of (logicially separated) commits on top of
+what's already in the archive.
+
 If you are lucky the other uploaders have also used dgit and
 integrated the other relevant git history; if not you can fetch it
 into your tree and cherry-pick etc. as you wish.
@@ -542,17 +577,17 @@ tree.
 
 dgit will automatically work around this for you when building and
 pushing.  The only thing you need to know is that dgit build, sbuild,
-etc., may make new commit (or, very occasionally, two) on your HEAD.
-If you're not a quilt user this commit won't contain any changes to
-files you care about.
+etc., may make new commits on your HEAD.  If you're not a quilt user
+this commit won't contain any changes to files you care about.
 
 You can explicitly request that dgit do just this fixup, by running
 dgit quilt-fixup.
 
-If you are a quilt user you need to know that dgit's git trees do not
-contain the .pc directory which is used by quilt to record which
-patches are applied.  If you want to manipulate the patch stack you
-probably want to be looking at tools like git-dpm.
+If you are a quilt user you need to know that dgit's git trees are
+`patches applied packaging branches' and do not contain the .pc
+directory (which is used by quilt to record which patches are
+applied).  If you want to manipulate the patch stack you probably want
+to be looking at tools like git-dpm.
 .SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT
 This section is mainly of interest to maintainers who want to use dgit
 with their existing git history for the Debian package.