Do not have .pc in dgit's git history for format `3.0 (quilt)'

packages.

 * When constructing a git tree from a .dsc (which we do by unpacking
   it in a temporary directory), drop any .pc directory.

 * Rewrite the quilt fixup preparation: we now fake up a .dsc so that
   we can regenerate the .pc, which is needed by dpkg-source.

 * If after we have committed any quilt fixup, there is a .pc
   directory, make a commit removing it.

 * We now construct new quilt patches in a temporary directory, so
   there is no problem about ignored files or --ignore-dirty.  Remove
   the mention of this limitation from the manpage.

 * Be less critical of `3.0 (quilt)' and improve the documentation
   relating to the interaction between dpkg-source and dgit.  Mention
   git-dpm.

 * When `committing quilty patches', do not re-add a deleted .pc
   directory (while still permitting updates to an existing .pc -
   although the .pc will then disappear in the next commit).

 * In the test suite, disregard differences found in .pc.

 * cmd_quilt_fixup sets $package for the benefit of
   build_maybe_quilt_fixup

1 files changed, 33 insertions, 49 deletions

diff --git a/dgit.1 b/dgit.1
index 4b27cda..1676bb8 100644
--- a/dgit.1
+++ b/dgit.1
@@ -183,10 +183,11 @@ the invocation host.  The build-host needs gnupg installed, with your
 public key in its keyring (but not your private key, obviously).
 .TP
 .B dgit quilt-fixup
-Looks to see if the tree is one which dpkg-source cannot properly
-represent.  If it isn't, dgit will fix it up for you (in quilt terms,
-by making a new debian/ patch containing your unquilty changes) and
-make a commit of the changes it has made.
+`3.0 (quilt)' format source packages need changes representing not
+only in-tree but also as patches in debian/patches.  dgit quilt-fixup
+checks whether this has been done; if not, dgit will make appropriate
+patches in debian/patches and also commit the resulting changes to
+git.
 
 This is normally done automatically by dgit build and dgit push.
 .TP
@@ -244,10 +245,6 @@ Do not complain if the working tree does not match your git HEAD.
 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.)
-
-This option may not work properly on `3.0 (quilt)' packages, as in
-that case dgit needs to use and perhaps commit parts of your working
-tree.
 .TP
 .BR --no-quilt-fixup
 Do not fix up source format `3.0 (quilt)' metadata.  If you use this
@@ -531,44 +528,31 @@ If you are not the maintainer, you do not need to worry about the
 source format of the package.  You can just make changes as you like
 in git.  If the package is a `3.0 (quilt)' package, the patch stack
 will usually not be represented in the git history.
-
-If you are the maintainer of a non-native package, you currently have
-two sensible options:
-
-Firstly, you can regard your git history as primary, and the archive
-as an export format.  For example, you could maintain topic branches
-in git and a fast-forwarding release branch; or you could do your work
-directly in a merging way on the
-.BI dgit/ suite
-branches.  If you do this you should probably use a `1.0' format
-source package if you can.  In the archive, the delta between upstream
-will be represented in the single Debian patch.
-
-Secondly, you can use `3.0 (quilt)', and 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.  But see below:
 .SH FORMAT 3.0 (QUILT)
 For a format `3.0 (quilt)' source package, dgit may have to make a
 commit on your current branch to contain metadata used by quilt and
 dpkg-source.
 
-This is because (i) the `3.0 (quilt)' source format cannot represent
-certain trees, and (ii) packing up a tree in `3.0 (quilt)' and then
-unpacking it does not always yield the same tree.  Instead,
-dpkg-source insists on the trees having extra quilty metadata and
-patch files in the debian/ and .pc/ directories, which dpkg-source
-sometimes modifies.
+This is because `3.0 (quilt)' source format represents the patch stack
+as files in debian/patches/ actually inside the source tree.  This
+means that, taking the whole tree (as seen by git or ls) (i)
+dpkg-source cannot represent certain trees, and (ii) packing up a tree
+in `3.0 (quilt)' and then unpacking it does not always yield the same
+tree.
 
-dgit will automatically work around this braindamage for you when
-building and pushing.  The only thing you need to know is that dgit
-build, sbuild, etc., may make a new commit on your HEAD.  If you're
-not a quilt user this commit won't contain any changes to files you
-care about.
+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.
 
 You can explicitly request that dgit do just this fixup, by running
 dgit quilt-fixup.
 
-We recommend against the use of `3.0 (quilt)'.
+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.
 .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.
@@ -698,16 +682,16 @@ Debian Maintainers are currently not able to push, as there is not
 currently any mechanism for determining and honouring the archive's
 ideas about access control.  Currently only DDs can push.
 
-dgit's representation of format `3.0 (quilt)' source packages does not
-represent the patch stack.  Currently the patch series representation
-cannot round trip through the archive.  Ideally dgit would represent a
-quilty package with an origin commit of some kind followed by the
-patch stack as a series of commits followed by a pseudo-merge (to make
-the branch fast-forwarding).  This would also mean a new `dgit
-rebase-prep' command or some such to turn such a fast-forwarding
-branch back into a rebasing patch stack, and a `force' option to dgit
-push (perhaps enabled automatically by a note left by rebase-prep)
-which will make the required pseudo-merge.
+dgit's git representation of format `3.0 (quilt)' source packages does
+not represent the patch stack as git commits.  Currently the patch
+series representation cannot round trip between git and the archive.
+Ideally dgit would represent a quilty package with an origin commit of
+some kind followed by the patch stack as a series of commits followed
+by a pseudo-merge (to make the branch fast-forwarding).  This would
+also mean a new `dgit rebase-prep' command or some such to turn such a
+fast-forwarding branch back into a rebasing patch stack, and a `force'
+option to dgit push (perhaps enabled automatically by a note left by
+rebase-prep) which will make the required pseudo-merge.
 
 If the dgit push fails halfway through, it should be restartable and
 idempotent.  However this is not true for the git tag operation.
@@ -721,11 +705,11 @@ Doing this is made more complicated by the possibility of a `3.0
 
 dgit's build functions, and dgit push, should not make any changes to
 your current HEAD.  Sadly this is necessary for packages in the `3.0
-(quilt)' source format.  This is ultimately due to design problems in
-quilt and dpkg-source.
+(quilt)' source format.  This is ultimately due to what I consider
+design problems in quilt and dpkg-source.
 
 There should be an option which arranges for the `3.0 (quilt)'
-autocommit to not appear on your HEAD, but instead only in the
+autocommit(s) to not appear on your HEAD, but instead only in the
 remote tracking suite branch.
 
 The option parser requires values to be cuddled to the option name.