Diffstat (limited to 'dgit.1')
1 files changed, 33 insertions, 49 deletions
@@ -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).
.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
This is normally done automatically by dgit build and dgit push.
@@ -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
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
-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
+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
-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
+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
-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.