diff options
Diffstat (limited to 'dgit.1')
| -rw-r--r-- | dgit.1 | 298 |
1 files changed, 221 insertions, 77 deletions
@@ -21,11 +21,11 @@ dgit \- git integration with the Debian archive [\fIdebbuildopts\fP] .br .B dgit -[\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP] +[\fIdgit\-opts\fP] \fBpush\fP|\fBpush-built\fP [\fIdgit\-opts\fP] [\fIsuite\fP] .br .B dgit -[\fIdgit\-opts\fP] \fBrpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR +[\fIdgit\-opts\fP] \fBrpush\fR|\fBrpush-built\fP \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR] .br .B dgit @@ -42,7 +42,7 @@ by ordinary people. This is the command line reference. Please read the tutorial(s): .TS -lb l. +lb2 l. dgit-user(7) for users: edit, build and share packages dgit-nmu-simple(7) for DDs: do a straightforward NMU dgit-maint-native(7) for maintainers of Debian-native packages @@ -192,10 +192,6 @@ passed on to sbuild. The output is left in .IR package \fB_\fR version \fB_multi.changes\fR. .IP -Note that by default -sbuild does not build arch-independent packages. -You probably want to pass \-A, to request those. -.IP Tagging, signing and actually uploading should be left to dgit push. .TP \fBdgit pbuilder\fR [\fIdebbuildopts\fP] @@ -238,17 +234,18 @@ 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] -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. 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. +\fBdgit push-source\fR [\fIsuite\fP] +Does an `upload': sends the current HEAD +to dgit-repos (as git commits), +and to the archive (as a source package, built by this command). -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, +This is the usual way to upload to Debian. It is like saying "update the +source code in the archive to match my git HEAD, and let the autobuilders do +the rest." + +In more detail: dgit push-source +builds a source package from HEAD. +It then pushes the HEAD to the suite's dgit-repos branch, adjusts the .changes to include any .origs which the archive lacks and exclude .origs which the archive has (so \-sa and \-sd are not needed when building for dgit push), @@ -265,21 +262,36 @@ When used on a git-debrebase branch, dgit calls git-debrebase to prepare the branch for source package upload and push. -.TP -\fBdgit push-source\fR [\fIsuite\fP] -Without \fB\-C\fR, builds a source package and dgit pushes it. Saying -\fBdgit push-source\fR is like saying "update the source code in the -archive to match my git HEAD, and let the autobuilders do the rest." -With \fB\-C\fR, performs a dgit push, additionally ensuring that no +With \fB\-C\fR, dgit push-source performs a dgit push-built, +additionally ensuring that no binary packages are uploaded. .TP -\fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR] +\fBdgit push-built\fR [\fIsuite\fP] +Does an `upload' of a previously built package, +possibly including binaries. +Sends the current HEAD to dgit-repos (as git commits); +and, sends the previously built source package and binaries +to the archive. + +The package must already +have been built ready for upload, with the .dsc and .changes +left in the parent directory. It is normally best to do the build +with dgit too (e.g. 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. + +dgit will check that the .dsc corresponds exactly to the current HEAD, +ensuring that all users, whether of the dgit git view, +or of the traditional archive, +see the same source package. +.TP +\fBdgit rpush-source\fR|\fBrpush-built\fR \fIbuild-host\fR\fB:\fR\fIsrc-dir\fR [\fIpush args...\fR] Pushes the contents of the specified directory on a remote machine. -This is like running dgit push on build-host with build-dir as the +This is like running dgit push on build-host with src-dir as the current directory; however, signing operations are done on the invoking host. This allows you to do a push when the system which has -the source code and the build outputs has no access to the key: +the source code (and any built binaries) has no access to the key: .TS l l. @@ -294,7 +306,8 @@ However, the build-host must be able to ssh to the dgit repos. If this is not already the case, you must organise it separately, for example by the use of ssh agent forwarding. -The remaining arguments are treated just as dgit push would handle +The remaining arguments are treated just as dgit push-source +or dgit push-built would handle them. build-host and build\-dir can be passed as separate @@ -306,6 +319,47 @@ You will need similar enough versions of dgit on the build-host and the invocation host. The build-host needs gnupg installed, with your public key in its keyring (but not your private key, obviously). .TP +\fBdgit push\fR|\fBrpush\fR \fI...\fP +Configurable aliases for +.BR "dgit push-built" +and +.BR "dgit rpush-built". +These aliases will in the future change to mean +.BR "dgit push-source" +and +.BR "dgit rpush-source" , +and therefore they currently generate a warning. + +The behaviour of dgit push is controlled by the +.B dgit.default.push-subcmd +git config option: +.TS +l l l . +\fBsource\fR runs \fBdgit push-source\fR future default +\fBbuilt\fR and runs \fBdgit push-built\fR +\fBbuilt,warn\fR warns, and runs \fBdgit push-built\fR current default +\fBreject\fR fails +.TE + +For dgit rpush, the behaviour is controlled by +.BR dgit.default.rpush-subcmd , +falling back to +.BR dgit.default.push-subcmd +if that is not set. +Because dgit rpush is not typically run in a git working tree, +only global git config options +(and \fB-c\fR command line options) are relevant. + +These settings can safely be passed to older dgit (via +.BR -c); +the value +.B built +will be supported indefinitely. +This should be used in scripts that need to work with both +old versions of dgit (that don't have \fBpush-built\fR) +and +new versions (where \fBpush-source\fR is the default). +.TP .B dgit setup-new-tree Configure the current working tree the way that dgit clone would have set it up. Like running @@ -495,17 +549,6 @@ See ACCESS CONFIGURATION, below. This function is primarily provided for the benefit of git-debrebase. .SH OPTIONS .TP -.BR \-\-dry-run " | " \-n -Go through the motions, fetching all information needed, but do not -actually update the output(s). For push, dgit does -the required checks and leaves the new .dsc in a temporary file, -but does not sign, tag, push or upload. -.TP -.BR \-\-damp-run " | " \-L -Go through many more of the motions: do everything that doesn't -involve either signing things, or making changes on the public -servers. -.TP .BI \-k keyid Use .I keyid @@ -630,11 +673,16 @@ fails even on ignored untracked files. This could perhaps be used to detect bugs in your rules clean target. .TP .BR -N " | " --new -The package is or may be new in this suite. Without this, dgit will +The package is, or may be, new in this suite. Without this, dgit will refuse to push. -It may (for Debian, will) be unable to access the git -history for any packages which have been newly pushed and have not yet -been published. +Needing --new is not unusual; for example, +it is frequently needed for uploading to Debian experimental. + +Note that dgit may be unable to access the git +history for an entirely new package which has not been accepted by +the archive. +So for an entirely new package you need to properly coordinate +with anyone else who might upload. .TP .BR --include-dirty Do not complain if the working tree does not match your git HEAD, @@ -659,7 +707,32 @@ combination can fail if the untracked files are under .BR --ignore-dirty Deprecated alias for --include-dirty. .TP -.BR --overwrite [=\fIprevious-version\fR] +.BR --collab-non-dgit +Make +.BR "dgit push" , +behave more suitably for collaborating +(using shared git history) +with git-using co-developers who aren't using dgit. + +With this option, +dgit won't mind that the git history you're using +isn't necessarily fast forward from the dgit view; +instead, it will rely on the changelog +to prevent accidentally overwriting changes. + +And, the +synthetic commits needed to +make the dgit git history fast forward +will appear only on the dgit git server, +and local dgit suite branches, +not on your own main branch. +So they won't end up in the maintainer-visible history, +when you push your own branch to make a merge request. + +This is equivalent to +.BR "--split-view=always --trust-changelog" . +.TP +.BR --trust-changelog " | " --overwrite =\fIprevious-version\fR Declare that your HEAD really does contain all the (wanted) changes from all versions listed in its changelog; @@ -670,40 +743,41 @@ your git branch is not a descendant of the version in the archive according to the git revision history. -It is safer not to specify -.IR previous-version , -and usually it's not needed. -Just say -.BR \-\-overwrite , -unless you know what you are doing. +It is safer to specify +.BR \-\-trust-changelog , +than +.BR \-\-overwrite= \fIprevious-version\fR, +and usually the latter is not needed. -This option is useful if you are the maintainer, and you have +.B --trust-changelog +is useful if you are the maintainer, and you have incorporated NMU changes into your own git workflow in a way that doesn't make your branch a fast forward from the NMU. It can also be useful when there was an upload made without dgit since the most recent upload made with dgit. -This option is also usually necessary +It is also usually necessary the first time a package is pushed with dgit push to a particular suite. See .BR dgit-maint- \fI*\fR (7) . -If -.I previous-version -is not -specified, dgit will check that the version in the archive is +With +.BR \-\-trust-changelog +dgit will check that the version in the archive is mentioned in your debian/changelog. (This will avoid losing -changes, even with -.BR --overwrite , +changes, unless someone committed to git a finalised changelog entry, and then made later changes to that version.) -If -.IR previous-version -is specified, it ought to be the version currently in the archive. -dgit push --overwrite +With +.BI \-\-overwrite= previous-version +that version ought to be the version currently in the archive, +and it will be unconditionally overwritten, +regardless of what's in the changelog. + +These options will, if necessary, make a pseudo-merge (that is, something that looks like the result of git merge -s ours) to stitch the archive's version into your own @@ -712,7 +786,13 @@ git history, so that your push is a fast forward from the archive. (In quilt mode .BR gbp ", " dpm ", " unpatched " or " baredebian *, implying a split between the dgit view and the -maintainer view, the pseudo-merge will appear only in the dgit view.) +maintainer view, the pseudo-merge will appear only in the dgit view; +.B --split-view=always +can be used to force that behaviour, e.g. in other quilt modes.) + +.B \-\-overwrite +without a version number is an obsolete way of specifying +.BR \-\-trust-changelog . .TP .BR \-\-delayed =\fIdays\fR Upload to a DELAYED queue. @@ -808,12 +888,12 @@ When split view is in operation, this also prevents the construction by dgit of a pseudomerge to make the dgit view fast forwarding. Normally only one of ---overwrite (which creates a suitable pseudomerge) +\-\-trust-changelog (which creates a suitable pseudomerge) and --deliberately-not-fast-forward (which suppresses the pseudomerge and the fast forward checks) should be needed; ---overwrite is usually better. +\-\-trust-changelog is usually better. .TP .BR --deliberately-include-questionable-history Declare that you are deliberately including, in the git history of @@ -830,8 +910,8 @@ throw away the existing repo. Not relevant when pushing to Debian, 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: one new patch for each relevant +With format `3.0 (quilt)', insist on +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. @@ -841,9 +921,10 @@ HEAD should be a series of plain commits 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 +.BR --quilt=try-linear +With format `3.0 (quilt)', +prefer +a linear patch stack (as with --quilt=linear) but if that doesn't seem possible, try to generate a single squashed patch for all the changes made in git @@ -851,7 +932,8 @@ try to 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, +With format `3.0 (quilt)', +assume patches-applied (as obtained from dgit clone) and generate a single additional patch for all the changes made in git. This is not a good idea for an NMU in Debian. @@ -861,18 +943,38 @@ if you do not change the upstream version nor make changes in debian/patches, it will remain true.) .TP +.BR --quilt=single +With format `3.0 (quilt)', +assume patches-applied (as obtained from dgit clone), +delete all the existing patches, and then +generate a single patch for all the changes made in git. +This is not a good idea for an NMU in Debian. + +Use this instead of the +.B single-debian-patch +dpkg-source format option. +That dpkg-source option cannot handle certain changes to the tree +that dpkg-source otherwise permits, +and in some cases it can generate strange source packages +that dpkg-source appears to accept +but which become corrupted when people later try to modify them. +.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 +With format `3.0 (quilt)', +assume patches-applied (as obtained from dgit clone), and +check that the patch metadata is up to date. +If it isn't, 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 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. +With format `3.0 (quilt)', +assume that the tree is patches-applied (as obtained from dgit clone), +and \fIassume\fR that the patch metadata is up to date. +If you use this option and the patch metadata is out of date, +dgit push will fail. .TP .BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied " | " -- [ quilt= ] baredebian [ +git | +tarball ] Tell dgit that you are using a nearly-dgit-compatible git branch, @@ -1087,6 +1189,15 @@ Obsolete alias for --dep14tag, retained for compatibility. Prints debugging information to stderr. Repeating the option produces more output (currently, up to -DDDD is meaningfully different). .TP +.BR \-\-keep\-playground | \-\-no\-\-keep\-playground +Controls whether to retain the "playground" working directory +.B .git/dgit/unpack +even on success, +for examination and debugging. +The default is +.B \-\-no\-keep\-playground +which deletes the directory after a successful execution. +.TP .BI -c name = value Specifies a git configuration option, to be used for this run. dgit itself is also controlled by git configuration options. @@ -1285,6 +1396,25 @@ removed and recreated before dgit starts, rather than removed after dgit finishes. The directory specified must be an absolute pathname. .TP +.BR \-\-dry-run " | " \-n +Go through the motions, fetching all information needed, but do not +actually update the output(s). For push, dgit does +the required checks and leaves the new .dsc in a temporary file, +but does not sign, tag, push or upload. + +This is not a very good simulation. +It can easily go wrong in ways that a for-real push wouldn't. +.TP +.BR \-\-damp-run " | " \-L +Go through many more of the motions: do everything that doesn't +involve either signing things, or making changes on the public +servers. + +Using this will make unsigned tags, +and possibly other local changes, +that will get in the way of a for-real push. +So be prepared to burn the version number you're using. +.TP .BI \-\-force- something Instructs dgit to try to proceed despite detecting what it thinks is going to be a fatal problem. @@ -1344,6 +1474,16 @@ when running gbp pq import when importing a package from a .dsc. See Debian bug #841867. .TP +.BR \-\-force-push-tainted +Go ahead and try to push even tainted git objects +hat the server says it is going to reject, +but without declaring any --deliberately. +This option is provided for testing or strange situations, +and is not the way to override the taint check: +using it will probably just fail later, +burning the version number you are using. +Use the appropriate --deliberately option instead. +.TP .BR \-\-for\-push Override the dgit-distro.distro.readonly configuration setting, to specify that we have read/write access @@ -1493,6 +1633,8 @@ or when pushing and .TP .BI dgit-distro. distro .git-check-suffix .TP +.BI dgit-distro. distro .policy-query-supported-ssh " " false | unknown | true +.TP .BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR .TP .BI dgit-distro. distro .git-create " " ssh-cmd | true @@ -1505,8 +1647,6 @@ or when pushing and .TP .BI dgit-distro. distro .archive-query-default-component .TP -.BI dgit-distro. distro .dgit-tag-format -.TP .BR dgit-distro. \fIdistro\fR .dep14tag " " want | no [| always ] .TP .BI dgit-distro. distro .ssh @@ -1529,6 +1669,10 @@ or when pushing and .TP .BI dgit.default.dsc-url-proto-ok .TP +.BI dgit.default.push-subcmd " " source | built | warn,built +Controls the behaviour of +.BR "dgit push" . +.TP .BR dgit.vcs-git.suites " \fIsuite\fR[" ; ...] .SH ENVIRONMENT VARIABLES .TP |