X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=98b525bca0809ae5472822a7a7130def9bac4b80;hp=42973a400380b6cfdee9ee4723293e2e86d8b553;hb=e1b329ed875a5d1cdd4666cf8dc66ae839324d9f;hpb=bee6f2e6f73394c340d37d22c3636fc5ffb4bf97 diff --git a/dgit.1 b/dgit.1 index 42973a40..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 @@ -445,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, @@ -496,6 +509,60 @@ 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). @@ -525,6 +592,11 @@ 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 @@ -631,57 +703,6 @@ git to access dgit-repos, only git's idea of what ssh to use (eg, .BR GIT_SSH ) is relevant. .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 @@ -704,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 @@ -919,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),