X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=98b525bca0809ae5472822a7a7130def9bac4b80;hp=a01590601fe7f9cb28b1f5bc0a3d8858bd2ceb24;hb=e1b329ed875a5d1cdd4666cf8dc66ae839324d9f;hpb=430c0a2bccc7427a981310da73061d2d4fe52bab diff --git a/dgit.1 b/dgit.1 index a0159060..98b525bc 100644 --- a/dgit.1 +++ b/dgit.1 @@ -1,3 +1,4 @@ +'\" t .TH dgit 1 "" "Debian Project" "dgit" .SH NAME dgit \- git integration with the Debian archive @@ -28,21 +29,23 @@ dgit \- git integration with the Debian archive .SH DESCRIPTION .B dgit allows you to treat the Debian archive as if it were a git -repository. See \fBdgit\fP(7) for detailed information about the data -model, common problems likely to arise with certain kinds of package, +repository. + +This is the command line reference. +Please read the tutorial(s): +.TS +lb l. +dgit-user(7) for users: editing, building and sharing packages +dgit-nmu-simple(7) for DDs/DMs: doing a straightforward NMU +dgit-maint-merge(7) for maintainers: using a merging git workflow +dgit-maint-gbp(7) for maintainers: using git-buildpackage +dgit-sponsorship(7) for sponsors and sponsored contributors +.TE +.LP +See \fBdgit(7)\fP for detailed information about the data +model, +common problems likely to arise with certain kinds of package, etc. - -The usual workflow is: -.br -1. \fBdgit clone\fR or \fBfetch\fR; -.br -2. make, do dev tests, and commit changes in git as desired; -.br -3. build packages for upload, using e.g. \fBdgit sbuild\fR -.br -4. do pre-upload tests of the proposed upload; -.br -5. \fBdgit push\fR. .SH OPERATIONS .TP \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR] @@ -376,7 +379,13 @@ maintainer view, the pseudo-merge will appear only in the dgit view.) 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 +which relate to distro-specific policies. +The use of --deliberately is declared and published in the signed tags +generated for you by dgit, +so that the archive software can give effect to your intent, +and +for the benefit humans looking at the history. +The meanings of .IR something s understood in the context of Debian are discussed below: .TP @@ -402,19 +411,35 @@ as the Debian server will do this automatically when necessary. .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. This is the default for Debian. +generating a linear patch stack: one new patch for each relevant +commit. +If such a stack cannot be generated, fail. +This is the default for Debian. + +HEAD should be a series of plain commits +(not touching debian/patches/), +and pseudomerges, +with as ancestor a patches-applied branch. .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. +generate a linear patch stack +(as with --quilt=auto) +but if that doesn't seem possible, +try to generate a single squashed patch for all the changes made in git +(as with --quilt=smash). 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. +generate a single additional patch for all the changes made in git. This is not a good idea for an NMU in Debian. + +(If HEAD has any in-tree patches already, they must apply cleanly. +This will be the case for any trees produced by dgit fetch or clone; +if you do not change the upstream version +nor make changes in debian/patches, +it will remain true.) .TP .BR --quilt=nofix Check whether source format `3.0 (quilt)' metadata would need fixing @@ -429,20 +454,24 @@ 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 -.BR --quilt=gbp " | " --quilt=dpm " | " --quilt=unapplied +.BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied Tell dgit that you are using a nearly-dgit-compatible git branch, aka a .BR "maintainer view" , and do not want your branch changed by dgit. -.B --quilt=gbp +.B --gbp +(short for +.BR --quilt=gbp ) is for use with git-buildpackage. Your HEAD is expected to be a patches-unapplied git branch, except that it might contain changes to upstream .gitignore files. This is the default for dgit gbp-build. -.B --quilt=dpm +.B --dpm +(short for +.BR --quilt=dpm ) is for use with git-dpm. Your HEAD is expected to be a patches-applied git branch, @@ -453,30 +482,87 @@ specifies that your HEAD is a patches-unapplied git branch (and that any changes to upstream .gitignore files are represented as patches in debian/patches). -Instead, dgit quilt-fixup and dgit-push will automatically -convert your git branch into the right form, -and dgit push will push the +With --quilt=gbp|dpm|unapplied, +dgit push (or precursors like quilt-fixup and build) will automatically +generate a conversion of your git branch into the right form. +dgit push will push the dgit-compatible form (the .BR "dgit view" ) to the dgit git server. The dgit view will be visible to you in the dgit remote tracking branches, but your own branch will not be modified. -dgit will create a tag +dgit push will create a tag .BI debian/ version for the maintainer view, and the dgit tag .BI archive/debian/ version for the dgit view. +dgit quilt-fixup will merely do some checks, +and cache the maintainer view. .B If you have a branch like this it is essential to specify the appropriate --quilt= option! This is because it is not always possible to tell: a patches-unapplied -git branch of a package with one patch, for example, looks just the -same as a patches-applied branch where the user has used git revert to +git branch of a package with one patch, for example, looks very like +a patches-applied branch where the user has used git revert to undo the patch, expecting to actually revert it. -If you fail to specify the right \-\-quilt option, +However, if you fail to specify the right \-\-quilt option, and you aren't too lucky, dgit will notice the problem and stop, with a useful hint. .TP +.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR +Specifies that the suite to be operated on is part of distro +.IR distro . +This overrides the default value found from the git config option +.BR dgit-suite. \fIsuite\fR .distro . +The only effect is that other configuration variables (used +for accessing the archive and dgit-repos) used are +.BR dgit-distro. \fIdistro\fR .* . + +If your suite is part of a distro that dgit already knows about, you +can use this option to make dgit work even if your dgit doesn't know +about the suite. For example, specifying +.B -ddebian +will work when the suite is an unknown suite in the Debian archive. + +To define a new distro it is necessary to define methods and URLs +for fetching (and, for dgit push, altering) a variety of information both +in the archive and in dgit-repos. +How to set this up is not yet documented. +.TP +.BI -C changesfile +Specifies the .changes file which is to be uploaded. By default +dgit push looks for single .changes file in the parent directory whose +filename suggests it is for the right package and version. + +If the specified +.I changesfile +pathname contains slashes, the directory part is also used as +the value for +.BR --build-products-dir ; +otherwise, the changes file is expected in that directory (by +default, in +.BR .. ). +.TP +.B --rm-old-changes +When doing a build, delete any changes files matching +.IB package _ version _*.changes +before starting. This ensures that +dgit push (and dgit sbuild) will be able to unambigously +identify the relevant changes files from the most recent build, even +if there have been previous builds with different tools or options. +The default is not to remove, but +.B \-\-no-rm-old-changes +can be used to override a previous \-\-rm-old-changes +or the .rm-old-changes configuration setting. +.TP +.BI --build-products-dir= directory +Specifies where to find the built files to be uploaded. +By default, dgit looks in the parent directory +.RB ( .. ). +.TP +.BI --no-rm-on-error +Do not delete the destination directory if clone fails. +.TP .BI -D Prints debugging information to stderr. Repeating the option produces more output (currently, up to -DDDD is meaningfully different). @@ -506,6 +592,55 @@ Passed to dpkg-genchanges (eventually). .RI \fB--ch:\fR option Specifies a single additional option to pass, eventually, to dpkg-genchanges. + +Options which are safe to pass include +.BR "-si -sa -sd -C" . + +For other options the caveat below applies. +.TP +.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..." +Specifies a single additional option to pass to +.BR curl , +.BR dput , +.BR debsign , +.BR dpkg-source , +.BR dpkg-buildpackage , +.BR dpkg-genchanges , +.BR sbuild , +.BR ssh , +.BR dgit , +.BR gbp-pq , +.BR gbp-build , +or +.BR mergechanges . +Can be repeated as necessary. + +Use of this ability should not normally be necessary. +It is provided for working around bugs, +or other unusual situations. +If you use these options, +you may violate dgit's assumptions +about the behaviour of its subprograms +and cause lossage. + +For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild, +the option applies only when the program is invoked directly by dgit. +Usually, for passing options to dpkg-genchanges, you should use +.BR --ch: \fIoption\fR. + +Specifying --git is not effective for some lower-level read-only git +operations performed by dgit, and also not when git is invoked by +another program run by dgit. + +See notes below regarding ssh and dgit. + +NB that --gpg:option is not supported (because debsign does not +have that facility). +But see +.B -k +and the +.B keyid +distro config setting. .TP .RI \fB--curl=\fR program " | \fB--dput=\fR" program " |..." Specifies alternative programs to use instead of @@ -568,93 +703,6 @@ git to access dgit-repos, only git's idea of what ssh to use (eg, .BR GIT_SSH ) is relevant. .TP -.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..." -Specifies a single additional option to pass to -.BR curl , -.BR dput , -.BR debsign , -.BR dpkg-source , -.BR dpkg-buildpackage , -.BR dpkg-genchanges , -.BR sbuild , -.BR ssh , -.BR dgit , -.BR gbp-pq , -.BR gbp-build , -or -.BR mergechanges . -Can be repeated as necessary. - -For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild, -this applies only when the program is invoked directly by dgit. -Usually, for passing options to dpkg-genchanges, you should use -.BR --ch: \fIoption\fR. - -Specifying --git not effective for some lower-level read-only git -operations performed by dgit, and also not when git is invoked by -another program run by dgit. - -See notes above regarding ssh and dgit. - -NB that --gpg:option is not supported (because debsign does not -have that facility). -But see -.B -k -and the -.B keyid -distro config setting. -.TP -.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR -Specifies that the suite to be operated on is part of distro -.IR distro . -This overrides the default value found from the git config option -.BR dgit-suite. \fIsuite\fR .distro . -The only effect is that other configuration variables (used -for accessing the archive and dgit-repos) used are -.BR dgit-distro. \fIdistro\fR .* . - -If your suite is part of a distro that dgit already knows about, you -can use this option to make dgit work even if your dgit doesn't know -about the suite. For example, specifying -.B -ddebian -will work when the suite is an unknown suite in the Debian archive. - -To define a new distro it is necessary to define methods and URLs -for fetching (and, for dgit push, altering) a variety of information both -in the archive and in dgit-repos. -How to set this up is not yet documented. -.TP -.BI -C changesfile -Specifies the .changes file which is to be uploaded. By default -dgit push looks for single .changes file in the parent directory whose -filename suggests it is for the right package and version. - -If the specified -.I changesfile -pathname contains slashes, the directory part is also used as -the value for -.BR --build-products-dir ; -otherwise, the changes file is expected in that directory (by -default, in -.BR .. ). -.TP -.B --rm-old-changes -When doing a build, delete any changes files matching -.IB package _ version _*.changes -before starting. This ensures that -dgit push (and dgit sbuild) will be able to unambigously -identify the relevant changes files from the most recent build, even -if there have been previous builds with different tools or options. -The default is not to remove, but -.B \-\-no-rm-old-changes -can be used to override a previous \-\-rm-old-changes -or the .rm-old-changes configuration setting. -.TP -.BI --build-products-dir= directory -Specifies where to find the built files to be uploaded. -By default, dgit looks in the parent directory -.RB ( .. ). -.TP .BI --existing-package= package dgit push needs to canonicalise the suite name. Sometimes, dgit lacks a way to ask the archive to do this without knowing the @@ -677,8 +725,34 @@ removed and recreated before dgit starts, rather than removed after dgit finishes. The directory specified must be an absolute pathname. .TP -.BI --no-rm-on-error -Do not delete the destination directory if clone fails. +.BI --force- something +Instructs dgit to try to proceed despite detecting +what it thinks is going to be a fatal problem. +.B This is probably not going to work. +These options are provided as an escape hatch, +in case dgit is confused. +(They might also be useful for testing error cases.) +.TP +.B --force-unrepresentable +Carry on even if +dgit thinks that your git tree contains changes +(relative to your .orig tarballs) +which dpkg-source is not able to represent. +Your build or push will probably fail later. +.TP +.B --force-unsupported-source-format +Carry on despite dgit not understanding your source package format. +dgit will probably mishandle it. +.TP +.B --force-dsc-changes-mismatch +Do not check whether .dsc and .changes match. +The archive will probably reject your upload. +.TP +.BR --force-import-gitapply-absurd " | " --force-import-gitapply-no-absurd +Force on or off the use of the absurd git-apply emulation +when running gbp pq import +when importing a package from a .dsc. +See Debian bug #841867. .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 @@ -892,41 +966,31 @@ and other subprograms and modules used by dgit are affected by various environment variables. Consult the documentaton for those programs for details. .SH BUGS -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. -Also, it would be good to check that the proposed signing key is +There should be +a `dgit rebase-prep' command or some such to turn a +fast-forwarding branch containing pseudo-merges +back into a rebasing patch stack. +It might have to leave a note +for a future dgit push. + +If the dgit push fails halfway through, +it is not necessarily restartable and +idempotent. +It would be good to check that the proposed signing key is available before starting work. -dgit's handling of .orig.tar.gz is not very sophisticated. Ideally -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. - -dgit's build functions, and dgit push, should not make any changes to +dgit's build functions, and dgit push, may make changes to your current HEAD. Sadly this is necessary for packages in the `3.0 (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(s) to not appear on your HEAD, but instead only in the -remote tracking suite branch. - --dry-run does not always work properly, as not doing some of the git fetches may result in subsequent actions being different. Doing a non-dry-run dgit fetch first will help. +--damp-run is likely to work much better. .SH SEE ALSO \fBdgit\fP(7), +\fBdgit-*\fP(7), \fBcurl\fP(1), \fBdput\fP(1), \fBdebsign\fP(1),