X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=72b16a05ba79dbfd528073ddc84a50bdeb54657f;hp=5895458a1722b0bf360662382f355b4577871344;hb=5fe77d980b7412ef6d0287590bc60003dbd3d18a;hpb=12dc1b71aa58bd4d044077b4f921580cedb0c347 diff --git a/dgit.1 b/dgit.1 index 5895458a..0da57f57 100644 --- a/dgit.1 +++ b/dgit.1 @@ -1,108 +1,346 @@ +'\" t .TH dgit 1 "" "Debian Project" "dgit" .SH NAME dgit \- git integration with the Debian archive . .SH SYNOPSIS .B dgit -[\fIdgit\-options\fP] \fBclone\fP [\fIdgit\-options\fP] -\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdest-dir|\fB/\fP\fIdest-dir] +[\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP] +\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR] .br .B dgit -[\fIdgit\-options\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-options\fP] +[\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP] [\fIsuite\fP] .br .B dgit -[\fIdgit\-options\fP] \fBbuild\fP -[\fIgit\-buildpackage\-options\fP|\fIdpkg\-buildpackage\-options\fp] +[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP +[\fIbuild\-opts\fp] .br .B dgit -[\fIdgit\-options\fP] \fBpush\fP [\fIdgit\-options\fP] +[\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP] [\fIsuite\fP] +.br +.B dgit +[\fIdgit\-opts\fP] \fBrpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR +[\fIpush args...\fR] +.br +.B dgit +[\fIdgit\-opts\fP] \fIaction\fR ... .SH DESCRIPTION .B dgit -treats the Debian archive as a version control system, and -bidirectionally gateways between the archive and git. The git view of -the package can contain the usual upstream git history, and will be -augmented by commits representing uploads done without using dgit. -This git history is stored in a canonical location -.B dgit-repos -which lives outside the Debian archive. - -.B dgit clone +allows you to treat the Debian archive as if it were a git +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: doing a straightforward NMU +dgit-maint-native(7) for maintainers of Debian-native packages +dgit-maint-merge(7) for maintainers who want a pure git workflow +dgit-maint-gbp(7) for maintainers already 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. +.SH OPERATIONS +.TP +\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR] +Consults the archive and dgit-repos to construct the git view of +history for +.I package +in +.I suite +.RB ( sid +by default) +in a new directory (named +.BI ./ package +by default); +also, downloads any necessary orig tarballs. + +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. +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. + +.I suite +may be a combination of several underlying suites in the form +.IR mainsuite \fB,\fR subsuite ...; +see COMBINED SUITES in dgit(7). + +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 +history for a specific suite (and downloads any necessary orig +tarballs), and updates the remote tracking branch +.BR remotes/dgit/dgit/ \fIsuite\fR. +If the current branch is +.BI dgit/ suite +then dgit fetch defaults to +.IR suite ; +otherwise it parses debian/changelog and uses the suite specified +there. +suite may be a combined suite, as for clone. +.TP +\fBdgit pull\fR [\fIsuite\fP] +Does dgit fetch, and then merges the new head of the remote tracking +branch +.BI remotes/dgit/dgit/ suite +into the current branch. +.TP +\fBdgit build\fR ... +Runs +.B dpkg-buildpackage +with some suitable options. Options and arguments after build +will be passed on to dpkg-buildpackage. It is not necessary to use +dgit build when using dgit; it is OK to use any approach which ensures +that the generated source package corresponds to the relevant git +commit. + +Tagging, signing and actually uploading should be left to dgit push. +.TP +\fBdgit build-source\fR ... +Builds the source package, and a changes file for a prospective +source-only upload, using +.BR dpkg-source . +The output is left in +.IR package \fB_\fR version \fB.dsc\fR and -.B dgit fetch -consult the archive and dgit-repos and fetch and/or construct the -git view of the history. With clone, the destination directory (by -default, the package name in the current directory) will be created, -and the new directory's `origin' remote will be set up to point to -the package's dgit-repos tree. - -.B dgit build -runs +.IR package \fB_\fR version \fB_source.changes\fR. + +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 +\fBdgit sbuild\fR ... +Constructs the source package, uses +.B sbuild +to do a binary build, and uses mergechanges to merge the source and +binary changes files. Options and arguments after sbuild will be +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 gbp-build\fR ... +Runs .B git-buildpackage -with some suitable options. Options after -.B build -will be passed on to git-buildpackage. It is not necessary to -use dgit build; it is OK to use any approach which ensures that -the generated source package corresponds to the relevant git commit. -Tagging and signing should be left to dgit push. - -.B dgit push -does an `upload', pushing the current HEAD to the archive (as a source -package) and to dgit-repos (as git commits). This also involves -making a signed git tag, and signing the files to be uploaded to the +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] +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. + +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, +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), +makes a signed git tag, edits the .dsc to contain the dgit metadata +field, runs debsign to sign the upload (.dsc and .changes), pushes the +signed tag, and finally uses dput to upload the .changes to the archive. -.SH MODEL AND WORKFLOW -You may use any suitable git workflow with dgit, provided you -satisfy dgit's requirements: -dgit maintains what looks a bit like a remote called -.BR dgit , -with one branch per suite. This remote cannot be used with -plain git. +dgit push always uses the package, suite and version specified in the +debian/changelog and the .dsc, which must agree. If the command line +specifies a suite then that must match too. +.TP +\fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-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 +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 -.B dgit-repos -repository for each package contains one ref per suite named -\fBdrefs/git/\fR\fIsuite\fR. These should be pushed to only by -dgit. They are fast forwarding. Each push on this branch -corresponds to an upload (or attempted upload). - -However, it is perfectly fine to have other branches in dgit-repos; -normally the dgit-repos repo for the package will be accessible via -the remote name `origin'. - -dgit push can operate on any commit which is a descendant of the -current dgit/suite tip in dgit-repos. - -Uploads made by dgit contain an additional field -.B Vcs-Git-Master -in the source package .dsc. (This is added by dgit push.) -This specifies a commit (an ancestor of the dgit/suite -branch) whose tree is identical to the unpacked source upload. - -Uploads not made by dgit are represented in git by commits which are -synthesised by dgit. The tree of each such commit corresponds to the -unpacked source; the single parent is the last known upload - that is, -the contents of the dgit/suite branch. - -dgit expects repos that it works with to have a -.B dgit -remote. This refers to the well-known dgit-repos location -(currently, the dgit-repos project on Alioth). dgit fetch updates -the remote tracking branch for dgit/suite. +.TS +l l. +1. Clone on build host (dgit clone) +2. Edit code on build host (edit, git commit) +3. Build package on build host (dgit build) +4. Test package on build host or elsewhere (dpkg -i, test) +5. Upload by invoking dgit rpush on host with your GPG key. +.TE + +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 +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 one in [ ], to support IPv6 address +literals). + +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 +.B dgit setup-new-tree +Configure the current working tree the way that dgit clone would have +set it up. Like running +.B dgit setup-useremail +and +.B setup-mergechangelogs +(but only does each thing if dgit is configured to do it automatically). +You can use these in any git repository, not just ones used with +the other dgit operations. +.TP +.B dgit setup-useremail +Set the working tree's user.name and user.email from the +distro-specific dgit configuration +.RB ( dgit-distro. \fIdistro\fR .user-name " and " .user-email ), +or DEBFULLNAME or DEBEMAIL. +.TP +.B dgit setup-mergechangelogs +Configures a git merge helper for the file +.B debian/changelog +which uses +.BR dpkg-mergechangelogs . +.TP +.B dgit quilt-fixup +`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 +\fBdgit import-dsc\fR [\fIsub-options\fR] \fI../path/to/.dsc\fR [\fB+\fR|\fB..\fR]branch +Import a Debian-format source package, +specified by its .dsc, +into git, +the way dgit fetch would do. + +This does about half the work of dgit fetch: +it will convert the .dsc into a new, orphan git branch. +Since dgit has no access to a corresponding source package archive +or knowledge of the history +it does not consider whether this version is newer +than any previous import +or corresponding git branches; +and it therefore does not +make a pseudomerge to bind the import +into any existing git history. + +Because a .dsc can contain a Dgit field naming a git commit +(which you might not have), +and specifying where to find that commit +(and any history rewrite table), +import-dsc might need online access. +If this is a problem +(or dgit's efforts to find the commit fail), +consider --no-chase-dsc-distro +or --force-import-dsc-with-dgit-field. + +There is only only sub-option: + +.B --require-valid-signature +causes dgit to insist that the signature on the .dsc is valid +(using the same criteria as dpkg-source -x). +Otherwise, dgit tries to verify the signature but +the outcome is reported only as messages to stderr. + +If +.I branch +is prefixed with +.B + +then if it already exists, it will be simply ovewritten, +no matter its existing contents. +If +.I branch +is prefixed with +.B .. +then if it already exists +and dgit actually imports the dsc +(rather than simply reading the git commit out of the Dgit field), +dgit will make a pseudomerge +so that the result is necessarily fast forward +from the existing branch. +Otherwise, if branch already exists, +dgit will stop with an error message. + +If +.I branch +does not start with refs/, refs/heads/ is prepended. +The specified branch is unconditionally updated. +.TP +.B dgit version +Prints version information and exits. +.TP +.BI "dgit clone-dgit-repos-server" " destdir" +Tries to fetch a copy of the source code for the dgit-repos-server, +as actually being used on the dgit git server, as a git tree. +.TP +.BI "dgit print-dgit-repos-server-source-url" +Prints the url used by dgit clone-dgit-repos-server. +This is hopefully suitable for use as a git remote url. +It may not be useable in a browser. .SH OPTIONS .TP -.BR --dry-run | -n +.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 -for signing the tag and the upload. +for signing the tag and the upload. The default comes from the +distro's +.B keyid +config setting (see CONFIGURATION, below), or failing that, the +uploader trailer line in debian/changelog. .TP .BR --no-sign does not sign tags or uploads (meaningful only with push). @@ -111,103 +349,787 @@ does not sign tags or uploads (meaningful only with push). .BI -p package Specifies that we should process source package .I package -rather than looking in debian/control. Valid with dgit fetch -and dgit pull, only. +rather than looking in debian/control or debian/changelog. +Valid with dgit fetch and dgit pull, only. .TP -.BI -D -Spew debugging information to stderr. +.BR --clean=git " | " -wg +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 -.BI -c name = value -Specifies a git configuration option. dgit itself is also controlled -by git configuration options. +.BR --clean=git-ff " | " -wgf +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). +Avoids running rules clean, +and can avoid needing the build-dependencies. +.TP +.BR --clean=none " | " -wn +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. +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 +is cleaned by dpkg-source running the package's clean target. +The build-dependencies are not checked (due to +.BR -d ), +which violates policy, but may work in practice. +.TP +.BR -N " | " --new +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. +.TP +.BR --ignore-dirty +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.) +.TP +.BR --overwrite =\fIprevious-version\fR +Declare that even though your git branch is not a descendant +of the version in the archive +according to the revision history, +it really does contain +all the (wanted) changes from that version. + +This option 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. + +.I previous-version +ought to be the version currently in the archive. If +.I previous-version +is not +specified, dgit will check that the version in the archive is +mentioned in your debian/changelog. +(This will avoid losing +changes unless someone committed to git a finalised changelog +entry, and then made later changes to that version.) + +dgit push --overwrite +will 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 +git history, so that your push is a fast forward from the archive. + +(In quilt mode +.BR gbp ", " dpm " or " unpatched , +implying a split between the dgit view and the +maintainer view, the pseudo-merge will appear only in the dgit view.) +.TP +.BR --delayed =\fIdays\fR +Upload to a DELAYED queue. + +.B WARNING: +If the maintainer responds by cancelling +your upload from the queue, +and does not make an upload of their own, +this will not rewind the git branch on the dgit git server. +Other dgit users will then see your push +(with a warning message from dgit) +even though the maintainer wanted to abolish it. +Such users might unwittingly reintroduce your changes. + +If this situation arises, +someone should make a suitable dgit push +to update the contents of dgit-repos +to a version without the controversial changes. .TP -.RI \fB--dget=\fR program |\fB--dput=\fR program |\fB--debsign=\fR program -Specifies alternative programs to use instead of dget, dput -or debsign. +.BR --no-chase-dsc-distro +Tells dgit not to look online +for additional git repositories +containing information about a particular .dsc being imported. +Chasing is the default. + +For most operations +(such as fetch and pull), +disabling chasing +means dgit will access only the git server +for the distro you are directly working with, +even if the .dsc was copied verbatim from another distro. +For import-dsc, +disabling chasing +means dgit will work completely offline. + +Disabling chasing can be hazardous: +if the .dsc names a git commit which has been rewritten +by those in charge of the distro, +this option may prevent that rewrite from being effective. +Also, +using it can mean that +dgit fails to find necessary git commits. +.TP +.BR --dgit-view-save= \fIbranch\fR|\fIref\fR +Specifies that when a split view quilt mode is in operation, +and dgit calculates +(or looks up in its cache) +a dgit view corresponding to your HEAD, +the dgit view will be left in +.IR ref . +The specified ref is unconditionally overwritten, +so don't specify a branch you want to keep. + +This option is effective only with the following operations: +quilt-fixup; push; all builds. +And it is only effective with +--[quilt=]gbp, +--[quilt=]dpm, +--quilt=unpatched. + +If ref does not start with refs/ +it is taken to to be a branch - +i.e. refs/heads/ is prepended. +.TP +.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 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 +.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 --deliberately-fresh-repo +Declare that you are deliberately rewinding history and want to +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 +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 +(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 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 +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 +.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 --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 --dpm +(short for +.BR --quilt=dpm ) +is for use with git-dpm. +Your HEAD is expected to be +a patches-applied git branch, +except that it might contain changes to upstream .gitignore files. + +.B --quilt=unapplied +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). + +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 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 very like +a patches-applied branch where the user has used git revert to +undo the patch, expecting to actually revert it. +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 -.RI \fB--dget:\fR option |\fB--dput:\fR option |\fB--debsign:\fR option -Specifies a single additional option to pass to dget, dput or -debsign. Use repeatedly if multiple additional options are required. +.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 they it is for the right package and version. +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 --dep14tag +Generates a DEP-14 tag (eg +.BR debian/ \fIversion\fR) +as well as a dgit tag (eg +.BR archive/debian/ \fIversion\fR) +where possible. This is the default. +.TP +.BI --no-dep14tag +Do not generate a DEP-14 tag, except in split quilt view mode. +(On servers where only the old tag format is supported, +the dgit tag will have the DEP-14 name. +This option does not prevent that.) +.TP +.BI --dep14tag-always +Insist on generating a DEP-14 tag +as well as a dgit tag. +If the server does not support that, dgit push will fail. +.TP +.BI -D +Prints debugging information to stderr. Repeating the option produces +more output (currently, up to -DDDD is meaningfully different). +.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. +.TP +.RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR +Specifies the +.BI -v version +option to pass to dpkg-genchanges, during builds. Changes (from +debian/changelog) since this version will be included in the built +changes file, and hence in the upload. If this option is not +specified, dgit will query the archive and use the latest version +uploaded to the intended suite. + +Specifying +.B _ +inhibits this, so that no -v option will be passed to dpkg-genchanges +(and as a result, only the last stanza from debian/changelog will +be used for the build and upload). +.TP +.RI \fB-m\fR maintaineraddress +Passed to dpkg-genchanges (eventually). +.TP +.RI \fB--ch:\fR option +Specifies a single additional option to pass, eventually, to +dpkg-genchanges. + +Options which are safe to pass include +.BR -C +(and also +.BR "-si -sa -sd" +although these should never be necessary with Debian since dgit +automatically calculates whether .origs need to be uploaded.) + +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 apt-get , +.BR apt-cache , +.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 , +.BR dput , +.BR debsign , +.BR dpkg-source , +.BR dpkg-buildpackage , +.BR dpkg-genchanges , +.BR sbuild , +.BR gpg , +.BR ssh , +.BR dgit , +.BR apt-get , +.BR apt-cache , +.BR git , +.BR gbp-pq , +.BR gbp-build , +or +.BR mergechanges . + +For +.BR dpkg-buildpackage , +.BR dpkg-genchanges , +.B mergechanges +and +.BR sbuild , +this applies only when the program is invoked directly by dgit. + +For +.BR 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 --dgit=). + +.BR gbp-build 's +value +is used instead of gbp build or git-buildpackage. (The default is +the latter unless the former exists on PATH.) +.BR gbp-pq 's +value +is used instead of gbp pq. +In both cases, +unusually, the specified value is split on whitespace +to produce a command and possibly some options and/or arguments. + +For +.BR ssh , +the default value is taken from the +.B DGIT_SSH +or +.B GIT_SSH +environment variables, if set (see below). And, for ssh, when accessing the +archive and dgit-repos, this command line setting is overridden by the +git config variables +.BI dgit-distro. distro .ssh +and +.B .dgit.default.ssh +(which can in turn be overridden with -c). Also, when dgit is using +git to access dgit-repos, only git's idea of what ssh to use (eg, +.BR GIT_SSH ) +is relevant. +.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 +name of an existing package. Without --new we can just use the +package we are trying to push. But with --new that will not work, so +we guess +.B dpkg +or use the value of this option. This option is not needed with the +default mechanisms for accessing the archive. +.TP +.BR -h | --help +Print a usage summary. +.TP +.BI --initiator-tempdir= directory +dgit rpush uses a temporary directory on the invoking (signing) host. +This option causes dgit to use +.I directory +instead. Furthermore, the specified directory will be emptied, +removed and recreated before dgit starts, rather than removed +after dgit finishes. The directory specified must be an absolute +pathname. +.TP +.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 --import-dsc-with-dgit-field +Tell dgit import-dsc to treat a .dsc with a Dgit field +like one without it. +The result is a fresh import, +discarding the git history +that the person who pushed that .dsc was working with. +.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-changes-origs-exactly +Use the set of .origs specified in your .changes, exactly, +without regard to what is in the archive already. +The archive may well reject your upload. +.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 CONFIGURATION -dgit looks at the following git config keys to control its behaviour. -You may set them with git-config (either in system-global or per-tree +dgit can be configured via the git config system. +You may set keys with git-config (either in system-global or per-tree configuration), or provide .BI -c key = value on the dgit command line. +.LP +Settings likely to be useful for an end user include: .TP -.BI dgit-suite. suite .distro +.BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR" +Specifies the distro for a suite. dgit keys off the suite name (which +appears in changelogs etc.), and uses that to determine the distro +which is involved. The config used is thereafter that for the distro. + +.I suite +may be a glob pattern. .TP -.BI dgit.default.distro +.BI dgit.default.distro " distro" +The default distro for an unknown suite. .TP -.BI dgit.default.username +.BI dgit.default.default-suite " suite" +The default suite (eg for clone). +.TP +.BR dgit.default. * +for each +.BR dgit-distro. \fIdistro\fR . *, +the default value used if there is no distro-specific setting. +.TP +.BR dgit-distro. \fIdistro\fR .clean-mode +One of the values for the command line --clean= option; used if +--clean is not specified. +.TP +.BR dgit-distro. \fIdistro\fR .quilt-mode +One of the values for the command line --quilt= option; used if +--quilt is not specified. +.TP +.BR dgit-distro. \fIdistro\fR .rm-old-changes +Boolean, used if neither \-\-rm-old-changes nor \-\-no-rm-old-changes +is specified. The default is not to remove. +.TP +.BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0 +Whether you have push access to the distro. +For Debian, it is OK to use auto, which uses readonly mode if you are +not pushing right now; +but, setting this to false will avoid relying on the mirror of the dgit +git repository server. +.TP +.BI dgit-distro. distro .keyid +See also +.BR -k . +.TP +.BI dgit-distro. distro .mirror " url" +.TP +.BI dgit-distro. distro .username +Not relevant for Debian. +.TP +.BI dgit-distro. distro .upload-host +Might be useful if you have an intermediate queue server. +.TP +.BI dgit-distro. distro .user-name " " dgit-distro. distro .user-email +Values to configure for user.name and user.email in new git trees. If +not specified, the DEBFULLNAME and DEBEMAIL environment variables are +used, respectively. Only used if .setup-usermail is not disabled. +.TP +.BI dgit-distro. distro .setup-useremail +Whether to set user.name and user.email in new git trees. +True by default. Ignored for dgit setup-setup-useremail, which does it anyway. +.TP +.BI dgit-distro. distro .setup-mergechangelogs +Whether to setup a merge driver which uses dpkg-mergechangelogs for +debian/changelog. True by default. Ignored for dgit +setup-mergechangelogs, which does it anyway. +.TP +.BI dgit-distro. distro .cmd- cmd +Program to use instead of +.IR cmd . +Works like +.BR -- \fIcmd\fR = "... ." +.TP +.BI dgit-distro. distro .opts- cmd +Extra options to pass to +.IR cmd . +Works like +.BR -- \fIcmd\fR : "... ." +To pass several options, configure multiple values in git config +(with git config --add). The options for +.BI dgit.default.opts- cmd +.BI dgit-distro. distro /push.opts- cmd +and are all used, followed by options from dgit's command line. +.SH ACCESS CONFIGURATION +There are many other settings which specify how a particular distro's +services (archive and git) are provided. These should not normally be +adjusted, but are documented for the benefit of distros who wish to +adopt dgit. +.TP +.BI dgit-distro. distro .nominal-distro +Shown in git tags, Dgit fields, and so on. +.TP +.BI dgit-distro. distro .alias-canon +Used for all access configuration lookup. +.TP +.BR dgit-distro. \fIdistro\fR /push. * +If set, overrides corresponding non \fB/push\fR config when +.BR readonly=false , +or when pushing and +.BR readonly=auto . .TP .BI dgit-distro. distro .git-url .TP -.BI dgit-distro. distro .git-host +.BR dgit-distro. \fIdistro\fR .git-url [ -suffix ] .TP .BI dgit-distro. distro .git-proto .TP .BI dgit-distro. distro .git-path .TP -.BI dgit-distro. distro .git-check +.BR dgit-distro. \fIdistro\fR .git-check " " true | false | url | ssh-cmd .TP -.BI dgit-distro. distro .git-create +.BI dgit-distro. distro .git-check-suffix .TP -.BI dgit-distro. distro .upload-host +.BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR +.TP +.BI dgit-distro. distro .git-create " " ssh-cmd | true +.TP +.BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR +.TP +.BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args ) .TP -.BI dgit-distro. distro .mirror +.BI dgit-distro. distro .madison-distro +.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 .TP -.BR dgit.default. * -for each -.BR dgit-distro. \fIdistro\fR . * +.BI dgit-distro. distro .sshpsql-dbname +.TP +.BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force ) +.TP +.BI dgit-distro. distro .backports-quirk +.TP +.BI dgit-distro. distro .rewrite-map-enable +.TP +.BI dgit.default.old-dsc-distro +.TP +.BI dgit.dsc-url-proto-ok. protocol +.TP +.BI dgit.dsc-url-proto-ok.bad-syntax +.TP +.BI dgit.default.dsc-url-proto-ok +.SH ENVIRONMENT VARIABLES +.TP +.BR DGIT_SSH ", " GIT_SSH +specify an alternative default program (and perhaps arguments) to use +instead of ssh. DGIT_SSH is consulted first and may contain arguments; +if it contains any whitespace will be passed to the shell. GIT_SSH +specifies just the program; no arguments can be specified, so dgit +interprets it the same way as git does. +See +also the --ssh= and --ssh: options. +.TP +.BR DEBEMAIL ", " DEBFULLNAME +Default git user.email and user.name for new trees. See +.BR "dgit setup-new-tree" . +.TP +.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. .SH BUGS -dgit will only work with packages in main. The madison http query API -does not give the component. - -dgit assumes knowledge of the archive layout. There appears to be no -sane way to find the path in the archive pool of the .dsc for a -particular suite. - -Debian Policy needs to be updated to describe the new Vcs-Git-Master -field (and to specify that it is an RC bug for that field to refer -to an unavailable commit). - -dgit push should perhaps do `git push origin', or something similar, -by default. +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. -The mechanism for checking for and creating per-package repos on -alioth is a hideous bodge. One consequence is that dgit currently -only works for people with push access. +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. -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 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. -dgit's representation of format `3.0 (quilt)' source packages (even if -they were supported) would 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) which will make -the required pseudo-merge. - -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. - -The error messages are often unhelpfully terse and tend to refer to -line numbers in dgit. - -The option parser requires values to be cuddled to the option name. - ---dry-run often does not work with fetch, even though this is a -logically plausible request. (It fails, instead.) +--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), +\fBgit-config\fP(1), +\fBgit-buildpackage\fP(1), +\fBdpkg-buildpackage\fP(1), +.br +https://browse.dgit.debian.org/