chiark / gitweb /
dgit-repos-policy-debian: WIP bugfixes to debugging
[dgit.git] / dgit.1
diff --git a/dgit.1 b/dgit.1
index 712f36dc80855d8b4e948f180fe4b85680eadbb8..35a09223fdeff8d7a025b15336c64c4f814ef256 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -59,12 +59,18 @@ The suite's git tip is
 left on the local branch
 .BI dgit/ suite
 ready for work, and on the corresponding dgit remote tracking branch.
-Also, the
+The
 .B origin
 remote will be set up to point to the package's dgit-repos tree
 for the distro to which
 .I suite
 belongs.
+
+For your convenience, the
+.B vcs-git
+remote will be set up from the package's Vcs-Git field, if there is
+one - but note that in the general case the history found there may be
+different to or even disjoint from dgit's view.
 .TP
 \fBdgit fetch\fR [\fIsuite\fP]
 Consults the archive and git-repos to update the git view of
@@ -106,6 +112,10 @@ and
 
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
+.B dgit clean
+Cleans the current working tree (according to the --clean= option in
+force).
+.TP
 .B dgit help
 Print a usage summary.
 .TP
@@ -133,7 +143,10 @@ Tagging, signing and actually uploading 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).  The package must already
 have been built ready for upload, with the .dsc and .changes
-left in the parent directory.
+left in the parent directory.  It is normally best to do the build
+with dgit too (eg with dgit sbuild): some existing build tools pass
+unhelpful options to dpkg-source et al by default, which can result in
+the built source package not being identical to the git tree.
 
 In more detail: dgit push checks that the current HEAD corresponds to
 the .dsc.  It then pushes the HEAD to the suite's dgit-repos branch,
@@ -165,19 +178,27 @@ them.
 
 build-host and build\-dir can be passed as separate
 arguments; this is assumed to be the case if the first argument
-contains no : (except perhaps on in [ ], to support IPv6 address
+contains no : (except perhaps one in [ ], to support IPv6 address
 literals).
 
 You will need similar enough versions of dgit on the build-host and
-the invocation host.
+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.
+
+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.
@@ -233,16 +254,59 @@ 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
-option and the package did in fact need fixing up, dgit push will
+.BI --deliberately- something
+Declare that you are deliberately doing
+.IR something .
+This can be used to override safety catches, including safety catches
+which relate to distro-specific policies.  The meanings of
+.IR something s
+understood in the context of Debian are discussed below:
+.TP
+.BR --deliberately-not-fast-forward
+Declare that you are deliberately rewinding history.  When pushing to
+Debian, use this when you are making a renewed upload of an entirely
+new source package whose previous version was not accepted for release
+from NEW because of problems with copyright or redistributibility.
+.TP
+.BR --deliberately-include-questionable-history
+Declare that you are deliberately including, in the git history of
+your current push, history which contains a previously-submitted
+version of this package which was not approved (or has not yet been
+approved) by the ftpmasters.  When pushing to Debian, only use this
+option after verifying that: none of the rejected-from-NEW (or
+never-accepted) versions in the git history of your current push, were
+rejected by ftpmaster for copyright or redistributability reasons.
+.TP
+.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 --quilt=nocheck | --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).
@@ -273,9 +337,9 @@ Passed to dpkg-genchanges (eventually).
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP
-.RI \fB--dget=\fR program |\fB--dput=\fR program |...
+.RI \fB--curl=\fR program |\fB--dput=\fR program |...
 Specifies alternative programs to use instead of
-.BR dget ,
+.BR curl ,
 .BR dput ,
 .BR debsign ,
 .BR dpkg-source ,
@@ -294,7 +358,7 @@ this applies only when the program is invoked directly by dgit.
 For dgit, specifies the command to run on the remote host when dgit
 rpush needs to invoke a remote copy of itself.  (dgit also reinvokes
 itself as the EDITOR for dpkg-source --commit; this is done using
-argv[0], and is not affected by --dget=).
+argv[0], and is not affected by --dgit=).
 
 For ssh, the default value is taken from the
 .B DGIT_SSH
@@ -311,9 +375,9 @@ git to access dgit-repos, only git's idea of what ssh to use (eg,
 .BR GIT_SSH )
 is relevant.
 .TP
-.RI \fB--dget:\fR option |\fB--dput:\fR option |...
+.RI \fB--curl:\fR option |\fB--dput:\fR option |...
 Specifies a single additional option to pass to
-.BR dget ,
+.BR curl ,
 .BR dput ,
 .BR debsign ,
 .BR dpkg-source ,
@@ -411,6 +475,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.
@@ -511,49 +580,40 @@ build and dgit push.
 To a user looking at the archive, changes pushed using dgit look like
 changes made in an NMU: in a `3.0 (quilt)' package the delta from the
 previous upload is recorded in a new patch constructed by dpkg-source.
+.SH READ-ONLY DISTROS
+Distros which do not maintain a set of dgit history git repositories
+can still be used in a read-only mode with dgit.  Currently Ubuntu
+is configured this way.
 .SH PACKAGE SOURCE FORMATS
 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 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.
 
-We recommend against the use of `3.0 (quilt)'.
+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.
@@ -658,7 +718,7 @@ interprets it the same way as git does.
 See
 also the --ssh= and --ssh: options.
 .TP
-.BR gpg ", " dpkg- "..., " debsign ", " git ", " dget ", " dput ", " LWP::UserAgent
+.BR gpg ", " dpkg- "..., " debsign ", " git ", " curl ", " dput ", " LWP::UserAgent
 and other subprograms and modules used by dgit are affected by various
 environment variables.  Consult the documentaton for those programs
 for details.
@@ -683,16 +743,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.
@@ -706,11 +766,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.
@@ -723,7 +783,7 @@ well-defined interface, let alone a secure one.)
 fetches may result in subsequent actions being different.  Doing a
 non-dry-run dgit fetch first will help.
 .SH SEE ALSO
-\fBdget\fP(1),
+\fBcurl\fP(1),
 \fBdput\fP(1),
 \fBdebsign\fP(1),
 \fBgit-config\fP(1),