deprecate 3.0 (quilt)

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index ad4be5f0e275f56753b028128ed6837a0c48e31b..c9705c7dc2d98c3cab55ab49e357d55785ccdf8a 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -52,8 +52,17 @@ Tagging and signing should be left to dgit push.
 does an `upload', pushing the current HEAD to the archive (as a source
 package) and to dgit-repos (as git commits).  This also involves
 making a signed git tag, and signing the files to be uploaded to the
-archive.  dgit push does a
-.BR "debian/rules clean" .
+archive.  (For a format `3.0 (quilt)' source package, dgit push
+may also have to make a commit on your current branch to contain
+quilt metadata.  It will do this automatically.)
+
+.B dgit quilt-fixup
+looks to see if there is quilt patch metadata left over by dpkg-source
+-b, and if so makes a git commit of it.  This is normally done
+automatically by dgit push.  dgit quilt-fixup takes no additional
+arguments.  Note that it will only process a patch generated by
+dpkg-source for the most recent version (according to the
+debia/changelog).
 .SH WORKFLOW - SIMPLE
 It is always possible with dgit to clone or fetch a package, make
 changes in git (using git-commit) on the suite branch
@@ -178,7 +187,9 @@ represented in the single Debian patch.
 
 Secondly, you can regard your quiltish patch stack in the archive as
 primary.  You will have to use other tools besides dgit to import and
-export this patch stack.  See also the BUGS section.
+export this patch stack.  For `3.0 (quilt)' packages, dgit has to do
+more work to work around quilt braindamage.  See also the BUGS
+section.  We recommend against the use of `3.0 (quilt)'.
 .SH OPTIONS
 .TP
 .BR --dry-run | -n
@@ -233,9 +244,6 @@ there is no way to ask the archive to do this without knowing the
 name of an existing package.  Without --new we can just use the
 package we are trying to push.  But with --new that will not work, so
 we guess that
-.TP
-.BI --clean-command= "cmd arg arg"
-dgit push needs to clean the tree to make sure the 
 .SH CONFIGURATION
 dgit looks at the following git config keys to control its behaviour.
 You may set them with git-config (either in system-global or per-tree
@@ -319,6 +327,15 @@ the .orig.tar.gz could be transported via the git repo as git tags.
 Doing this is made more complicated by the possibility of a `3.0
 (quilt)' package with multiple .orig tarballs.
 
+`3.0 (quilt)' packages have an additional difficulty: if these are
+edited in the most normal way, and then fed to dpkg-buildpackage,
+dpkg-source will add extra quilt patch metadata to the source tree
+during the source package build.  This extra metadata is then of
+course not included in the git history.  So dgit push needs to commit
+it for you, to make sure that the git history and archive contents are
+identical.  That this is necessary is a bug in the `3.0 (quilt)'
+format.
+
 The error messages are often unhelpfully terse and tend to refer to
 line numbers in dgit.