X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=c569347e658bb6480e12072b0985c5dcef4670e1;hp=e4da7f23b4883b200102994152cf34ac9fba80f9;hb=86a8ff1a0f02829b07bf7cd2fdd198ce612b37d4;hpb=71d71cb4e886f068fe5c6f29f265a4ff47df13d1

diff --git a/dgit.1 b/dgit.1
index e4da7f23..c569347e 100644
--- a/dgit.1
+++ b/dgit.1
@@ -34,17 +34,15 @@ etc.
 
 The usual workflow is:
 .br
-1.	dgit clone or fetch
+1.	\fBdgit clone\fR or \fBfetch\fR;
 .br
-2.	make, dev test and commit changes in git as desired
+2.	make, do dev tests, and commit changes in git as desired;
 .br
-3.	run dgit build, dgit sbuild or 
-dgit build-source, or generate the source and binary packages for upload
-some other way
+3.	build packages for upload, using e.g. \fBdgit sbuild\fR
 .br
-4.	do pre-upload tests of the proposed upload
+4.	do pre-upload tests of the proposed upload;
 .br
-5.	dgit push.
+5.	\fBdgit push\fR.
 .SH OPERATIONS
 .TP
 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
@@ -200,6 +198,14 @@ 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-mergechangelogs
+Configures a git merge helper for the file
+.B debian/changelog
+which uses
+.BR dpkg-mergechangelogs .
+You can use this in any git repository, not just ones used with
+the other dgit operations.
+.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
@@ -223,13 +229,13 @@ 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.
 .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
+.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.
@@ -249,7 +255,7 @@ Specifies that we should process source package
 rather than looking in debian/control or debian/changelog.
 Valid with dgit fetch and dgit pull, only.
 .TP
-.BR --clean=git | -wg
+.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" .
@@ -263,17 +269,26 @@ from being run.
 the downside is simply that git clean may delete files you forgot to
 git add.
 .TP
-.BR --clean=none | -wn
+.BR --clean=git-ff " | " -wgf
+The source tree should be cleaned, before building a source package
+with one of the build options, using
+.BR "git clean -xdff" .
+This is 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=none " | " -wn
 Do not clean the tree before building a source package.  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
+.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.  It requires the package's build dependencies.
 .TP
-.BR -N | --new
+.BR -N " | " --new
 The package may be new in this suite.  Without this, dgit will
 refuse to push.
 .TP
@@ -335,7 +350,7 @@ because the dgit git tree does not have a
 .B .pc
 directory.)
 .TP
-.BR --quilt=nocheck | --no-quilt-fixup
+.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.
@@ -370,7 +385,7 @@ Passed to dpkg-genchanges (eventually).
 Specifies a single additional option to pass, eventually, to
 dpkg-genchanges.
 .TP
-.RI \fB--curl=\fR program |\fB--dput=\fR program |...
+.RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
 Specifies alternative programs to use instead of
 .BR curl ,
 .BR dput ,
@@ -408,7 +423,7 @@ git to access dgit-repos, only git's idea of what ssh to use (eg,
 .BR GIT_SSH )
 is relevant.
 .TP
-.RI \fB--curl:\fR option |\fB--dput:\fR option |...
+.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
 Specifies a single additional option to pass to
 .BR curl ,
 .BR dput ,
@@ -622,25 +637,8 @@ 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.
-
-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 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
-only works for people with push access.
-
-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.
+Debian Maintainers are currently not able to push, as the project
+lacks a list of their ssh keys (!)
 
 dgit's git representation of format `3.0 (quilt)' source packages does
 not represent the patch stack as git commits.  Currently the patch
@@ -674,10 +672,6 @@ remote tracking suite branch.
 
 The option parser requires values to be cuddled to the option name.
 
-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
 non-dry-run dgit fetch first will help.