X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=7e74d5b77f62fdfc2ad5782c3973e8b9b4907c62;hp=1abb7ecdc11480d587611eafd5e5373e4bf4aac6;hb=d198bbd72d591b6deba779a8d24cf9bc9ae80894;hpb=a5ea919cd9bc80267bb1071b41a90e981ada6032

diff --git a/dgit.1 b/dgit.1
index 1abb7ecd..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
@@ -82,40 +86,50 @@ into the current branch.
 .TP
 \fBdgit build\fR ...
 Runs
-.B git-buildpackage
+.B dpkg-buildpackage
 with some suitable options.  Options and argumments after build
-will be passed on to git-buildpackage.  It is not necessary to use
+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.
 
-.B NB
-that this function will be changed in the future to use
-dpkg-buildpackage directly.
-
 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.  The output is left in
+source-only upload, using
+.BR dpkg-source .
+The output is left in
 .IR package \fB_\fR version \fB.dsc\fR
 and
 .IR package \fB_\fR version \fB_source.changes\fR.
 
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
+.B dgit help
+Print a usage summary.
+.TP
 \fBdgit sbuild\fR ...
-Constructs the source package, and uses sbuild to do a binary
-build, and uses mergechanges to merge the source and binary
-changes files.  Options and argumments after sbuild will be passed on
-to sbuild.  Changes files matching
+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 argumments after sbuild will be
+passed on to sbuild.  Changes files matching
 .IB package _ version _*.changes
 in the parent directory will be removed; the output is left in
 .IR package \fB_\fR version \fB_multi.changes\fR.
 
 Tagging, signing and actually uploading should be left to dgit push.
 .TP
-.B dgit push
+\fBdgit git-build\fR ...
+Runs
+.B git-buildpackage
+with some suitable options.  Options and argumments after git-build
+will be passed on to git-buildpackage.
+
+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
@@ -129,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,
@@ -141,6 +175,212 @@ 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
+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.
+.TP
+.BR --no-sign
+does not sign tags or uploads (meaningful only with push).
+.TP
+.TP
+.BI -p package
+Specifies that we should process source package
+.I package
+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.
+.TP
+.BR --clean=none | -wn
+Do not clean the tree before building a source package.  If there are
+files which are not in git, a subsequent dgit push will fail.
+.TP
+.BR --clean=dpkg-source | -wd
+Use dpkg-buildpackage to do the build, 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.
+.TP
+.BR -N | --new
+The package may be new in this suite.  Without this, dgit will
+refuse to push.
+.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.)
+
+This option may not work properly on `3.0 (quilt)' packages, as in
+that case dgit needs to use and perhaps commit parts of your working
+tree.
+.TP
+.BR --no-quilt-fixup
+Do not fix up source format `3.0 (quilt)' metadata.  If you use this
+option and the package did in fact need fixing up, dgit push will
+fail.
+.TP
+.BI -D
+Prints debugging information to stderr.  Repeating the option produces
+more output (currently, up to -DD is meaningfully different).
+.TP
+.BI -c name = value
+Specifies a git configuration option.  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.
+.TP
+.RI \fB--dget=\fR program |\fB--dput=\fR program |...
+Specifies alternative programs to use instead of
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.BR sbuild ,
+.BR gpg ,
+.BR ssh ,
+.BR dgit ,
+or
+.BR mergechanges .
+
+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
+.BR dget ,
+.BR dput ,
+.BR debsign ,
+.BR dpkg-source ,
+.BR dpkg-buildpackage ,
+.BR dpkg-genchanges ,
+.BR sbuild ,
+.BR ssh ,
+.BR dgit ,
+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.
+
+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
+.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 do this is not yet
+documented, and currently the arrangements are unpleasant.  See
+BUGS.
+.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 - or,
+if there is a _multi.changes file, dgit uses that.
+.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.
 .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
@@ -225,7 +465,7 @@ 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-Dgit-Master
+.B Dgit
 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.
@@ -242,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
@@ -293,139 +534,51 @@ You can explicitly request that dgit do just this fixup, by running
 dgit quilt-fixup.
 
 We recommend against the use of `3.0 (quilt)'.
-.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
-.BI -k keyid
-Use
-.I keyid
-for signing the tag and the upload.
-.TP
-.BR --no-sign
-does not sign tags or uploads (meaningful only with push).
-.TP
-.TP
-.BI -p package
-Specifies that we should process source package
-.I package
-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.
-.TP
-.BR --clean=none | -wn
-Do not clean the tree before building a source package.  If there are
-files which are not in git, a subsequent dgit push will fail.
-.TP
-.BR --clean=dpkg-source | -wd
-Use dpkg-buildpackage to do the build, 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.
-.TP
-.BR -N | --new
-The package may be new in this suite.  Without this, dgit will
-refuse to push.
-.TP
-.BI -D
-Prints debugging information to stderr.  Repeating the option produces
-more output (currently, up to -DD is meaningfully different).
-.TP
-.BI -c name = value
-Specifies a git configuration option.  dgit itself is also controlled
-by git configuration options.
-.TP
-.RI \fB-v\fR version |\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.
-.TP
-.RI \fB--dget=\fR program |\fB--dput=\fR program |...
-Specifies alternative programs to use instead of
-.BR dget ,
-.BR dput ,
-.BR debsign ,
-.BR dpkg-source ,
-.BR dpkg-buildpackage ,
-.BR dpkg-genchanges ,
-.BR sbuild ,
-or
-.BR mergechanges .
-This applies only when the program is invoked directly by dgit.
-.TP
-.RI \fB--dget:\fR option |\fB--dput:\fR option |...
-Specifies a single additional option to pass to
-.BR dget ,
-.BR dput ,
-.BR debsign ,
-.BR dpkg-source ,
-.BR dpkg-buildpackage ,
-.BR dpkg-genchanges ,
-.BR sbuild ,
-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
-.BR --ch: \fIoption\fR.
-.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 do this is not yet
-documented, and currently the arrangements are unpleasant.  See
-BUGS.
-.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 - 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
-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.
-.TP
-.BR -h | --help
-Print a usage summary.
-.SH SEE ALSO
-\fBdget\fP(1),
-\fBdput\fP(1),
-\fBdebsign\fP(1),
-\fBgit-config\fP(1),
-\fBgit-buildpackage\fP(1),
-\fBdpkg-buildpackage\fP(1),
-.br
-https://wiki.debian.org/Alioth
+.SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT
+This section is mainly of interest to maintainers who want to use dgit
+with their existing git history for the Debian package.
+
+Some developers like to have an extra-clean git tree which lacks files
+which are normally found in source tarballs and therefore in Debian
+source packages.  For example, it is conventional to ship ./configure
+in the source tarball, but some people prefer not to have it present
+in the git view of their project.
+
+dgit requires that the source package unpacks to exactly the same
+files as are in the git commit on which dgit push operates.  So if you
+just try to dgit push directly from one of these extra-clean git
+branches, it will fail.
+
+As the maintainer you therefore have the following options:
+.TP
+\(bu
+Persuade upstream that the source code in their git history and the
+source they ship as tarballs should be identical.  Of course simply
+removing the files from the tarball may make the tarball hard for
+people to use.
+.IP
+One answer is to commit the (maybe autogenerated)
+files, perhaps with some simple automation to deal with conflicts and
+spurious changes.  This has the advantage that someone who clones
+the git repository finds the program just as easy to build as someone
+who uses the tarball.
+.TP
+\(bu
+Have separate git branches which do contain the extra files, and after
+regenerating the extra files (whenever you would have to anyway),
+commit the result onto those branches.
+.TP
+\(bu
+Provide source packages which lack the files you don't want
+in git, and arrange for your package build to create them as needed.
+This may mean not using upstream source tarballs and makes the Debian
+source package less useful for people without Debian build
+infrastructure.
+.LP
+Of course it may also be that the differences are due to build system
+bugs, which cause unintended files to end up in the source package.
+dgit will notice this and complain.  You may have to fix these bugs
+before you can unify your existing git history with dgit's.
 .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
@@ -461,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
@@ -474,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 Vcs-Dgit-Master
-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
@@ -532,16 +693,21 @@ 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 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.
+.SH SEE ALSO
+\fBdget\fP(1),
+\fBdput\fP(1),
+\fBdebsign\fP(1),
+\fBgit-config\fP(1),
+\fBgit-buildpackage\fP(1),
+\fBdpkg-buildpackage\fP(1),
+.br
+https://wiki.debian.org/Alioth