X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=42973a400380b6cfdee9ee4723293e2e86d8b553;hp=b3a4f9392be39fac79845503c5295aa5eda7c4d7;hb=8ff24012c9e4b826cedca7eada4476abf518ccd5;hpb=908517686fdd444ee9a04abe871c747e7bac03d5 diff --git a/dgit.1 b/dgit.1 index b3a4f939..42973a40 100644 --- a/dgit.1 +++ b/dgit.1 @@ -139,6 +139,9 @@ Runs with some suitable options. Options and arguments after gbp-build will be passed on to git-buildpackage. +By default this uses \-\-quilt=gbp, so HEAD should be a +git-buildpackage style branch, not a patches-applied branch. + Tagging, signing and actually uploading should be left to dgit push. .TP \fBdgit push\fR [\fIsuite\fP] @@ -273,46 +276,53 @@ rather than looking in debian/control or debian/changelog. Valid with dgit fetch and dgit pull, only. .TP .BR --clean=git " | " -wg -The source tree should be cleaned, before building a source package -with one of the build options, using -.BR "git clean -xdf" . -This will delete all files which are not tracked by git. Also, -wg -causes dgit to pass -.B -nc -to dpkg-buildpackage, which prevents the package's own clean target -from being run. - ---clean=git is useful when the package's clean target is troublesome; -the downside is simply that git clean may delete files you forgot to -git add. --clean=git can also avoid needing the build-dependencies. +Use +.BR "git clean -xdf" +to clean the working tree, +rather than running the package's rules clean target. + +This will delete all files which are not tracked by git. +(Including any files you forgot to git add.) + +.BI --clean= ... +options other than dpkg-source +are useful when the package's clean target is troublesome, or +to avoid needing the build-dependencies. .TP .BR --clean=git-ff " | " -wgf -The source tree should be cleaned, before building a source package -with one of the build options, using -.BR "git clean -xdff" . -This is like -"git clean -xdf" +Use +.BR "git clean -xdff" +to clean the working tree. +Like +git clean -xdf but it also removes any subdirectories containing different git trees (which only unusual packages are likely to create). .TP .BR --clean=check " | " -wc Merely check that the tree is clean (does not contain uncommitted -files), before building a source package. +files). +Avoids running rules clean, +and can avoid needing the build-dependencies. .TP .BR --clean=none " | " -wn -Do not clean the tree before building a source package. If there are +Do not clean the tree, nor check that it is clean. +Avoids running rules clean, +and can avoid needing the build-dependencies. +If there are files which are not in git, or if the build creates such files, a subsequent dgit push will fail. .TP .BR --clean=dpkg-source " | " -wd Use dpkg-buildpackage to do the clean, so that the source package is cleaned by dpkg-source running the package's clean target. -This is the default. It requires the package's build dependencies. +This is the default. +Requires the package's build dependencies. .TP .BR --clean=dpkg-source-d " | " -wdd Use .B dpkg-buildpackage -d -to do the clean, so that the source package +to do the clean, +so that the source package is cleaned by dpkg-source running the package's clean target. The build-dependencies are not checked (due to .BR -d ), @@ -392,19 +402,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 @@ -430,7 +456,7 @@ do not want your branch changed by dgit. 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. +to upstream .gitignore files. This is the default for dgit gbp-build. .B --quilt=dpm is for use with git-dpm. @@ -443,27 +469,30 @@ 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 @@ -497,6 +526,50 @@ Passed to dpkg-genchanges (eventually). Specifies a single additional option to pass, eventually, to dpkg-genchanges. .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 .BR curl , @@ -558,42 +631,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 .