X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=7e74d5b77f62fdfc2ad5782c3973e8b9b4907c62;hp=95923d38ffac03ac8114cf980c0a5367ded2a5a0;hb=d198bbd72d591b6deba779a8d24cf9bc9ae80894;hpb=826d944a64972ded735a10eb0b11fd69e76fefbf diff --git a/dgit.1 b/dgit.1 index 95923d38..7e74d5b7 100644 --- a/dgit.1 +++ b/dgit.1 @@ -20,6 +20,10 @@ dgit \- git integration with the Debian archive [\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 @@ -125,7 +129,7 @@ will be passed on to git-buildpackage. Tagging, signing and actually uploading should be left to dgit push. .TP -.B dgit push +\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 @@ -139,11 +143,31 @@ signed tag, and finally uses dput to upload the .changes to the archive. dgit push always uses the package, suite and version specified in the -debian/changelog and the .dsc, which must agree. +debian/changelog and the .dsc, which must agree. If the command line +specifies a suite then that must match too. If dgit push fails while uploading, it is fine to simply retry the dput on the .changes file at your leisure. .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. + +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 on in [ ], to support IPv6 address +literals). +.TP .B dgit quilt-fixup Looks to see if the tree is one which dpkg-source cannot properly represent. If it isn't, dgit will fix it up for you (in quilt terms, @@ -151,6 +175,9 @@ by making a new debian/ patch containing your unquilty changes) and make a commit of the changes it has made. This is normally done automatically by dgit build and dgit push. +.TP +.B dgit version +Prints version information and exits. .SH OPTIONS .TP .BR --dry-run | -n @@ -159,6 +186,11 @@ 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 @@ -216,7 +248,22 @@ more output (currently, up to -DD is meaningfully different). Specifies a git configuration option. dgit itself is also controlled by git configuration options. .TP -.RI \fB-v\fR version |\fB-m\fR maintaineraddress +.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 @@ -232,9 +279,34 @@ Specifies alternative programs to use instead of .BR dpkg-buildpackage , .BR dpkg-genchanges , .BR sbuild , +.BR gpg , +.BR ssh , +.BR dgit , or .BR mergechanges . -This applies only when the program is invoked directly by dgit. + +For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild, +this applies only when the program is invoked directly by dgit. + +For 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 --dget=). + +For 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 .RI \fB--dget:\fR option |\fB--dput:\fR option |... Specifies a single additional option to pass to @@ -245,12 +317,21 @@ Specifies a single additional option to pass to .BR dpkg-buildpackage , .BR dpkg-genchanges , .BR sbuild , +.BR ssh , +.BR dgit , or .BR mergechanges . Can be repeated as necessary. -This applies only when the program is invoked directly by dgit. -Usually, for passing options to dpkg-genchanges, use + +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. + +See notes above regarding ssh and dgit. + +NB that --gpg:option is not supported (because debsign does not +have that facility). But see -k. .TP .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR Specifies that the suite to be operated on is part of distro @@ -280,16 +361,26 @@ filename suggests it is for the right package and version - or, if there is a _multi.changes file, dgit uses that. .TP .BI --existing-package= package -dgit push needs to canonicalise the suite name. But currently -there is no way to ask the archive to do this without knowing the +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. +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. .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 @@ -391,10 +482,11 @@ 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. -dgit does not (currently) represent the orig tarball(s) in git; nor -does it represent the patch statck of a `3.0 (quilt)' package. The -orig tarballs are downloaded and kept in the parent directory, as with -a traditional (non-gitish) dpkg-source workflow. +dgit does not (currently) represent the orig tarball(s) in git. The +orig tarballs are downloaded (by dgit clone) into the parent +directory, as with a traditional (non-gitish) dpkg-source workflow. +You need to retain these tarballs in the parent directory for dgit +build and dgit push. To a user looking at the archive, changes pushed using dgit look like changes made in an NMU: in a `3.0 (quilt)' package the delta from the @@ -522,11 +614,11 @@ on the dgit command line. .TP .BI dgit-distro. distro .archive-query-default-component .TP -.BI dgit-distro. distro .sshdakls-user +.BI dgit-distro. distro .sshpsql-user .TP -.BI dgit-distro. distro .sshdakls-host +.BI dgit-distro. distro .sshpsql-host .TP -.BI dgit-distro. distro .sshdakls-dir +.BI dgit-distro. distro .sshpsql-dbname .TP .BI dgit-distro. distro .ssh .TP @@ -535,25 +627,33 @@ on the dgit command line. .BR dgit.default. * for each .BR dgit-distro. \fIdistro\fR . * +.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 gpg ", " dpkg- "..., " debsign ", " git ", " dget ", " 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 We should be using some kind of vhost/vpath setup for the git repos on alioth, so that they can be moved later if and when this turns out to be a good idea. -Debian Policy needs to be updated to describe the new Dgit .dsc -field (and to specify that it is an RC bug for that field to refer -to an unavailable commit). - -The method of canonicalising suite names is bizarre. See the -.B --existing-package -option for one of the implications. - dgit push should perhaps do `git push origin', or something similar, by default. Debian does not have a working rmadison server, so to find out what version of a package is in the archive, or to canonicalise suite -names, we ssh directly into the ftpmaster server. +names, we ssh directly into the ftpmaster server and run psql there to +access the database. The mechanism for checking for and creating per-package repos on alioth is a hideous bodge. One consequence is that dgit currently @@ -593,16 +693,11 @@ There should be an option which arranges for the `3.0 (quilt)' autocommit to not appear on your HEAD, but instead only in the remote tracking suite branch. -There should at the very least be some advice in the manpage about how -to use dgit when the signing key is not available on the same machine -as the build host. - The option parser requires values to be cuddled to the option name. -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. I'm assured that the archive layout is a -`well known algorithm' by now. +dgit assumes knowledge of the archive database. (The information dgit +needs is not currently available via any public online service with a +well-defined interface, let alone a secure one.) --dry-run does not always work properly, as not doing some of the git fetches may result in subsequent actions being different. Doing a