X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=dgit.1;h=31cfa5a86e1d9d5c862cac40a72faaf83f0cfb5f;hb=184d3eea8478dd234f69516b1192c9bb35d62ab8;hp=ad4be5f0e275f56753b028128ed6837a0c48e31b;hpb=c49ed487a8eba41e990e483dc1851c817ed5237a;p=dgit.git

diff --git a/dgit.1 b/dgit.1
index ad4be5f0..31cfa5a8 100644
--- a/dgit.1
+++ b/dgit.1
@@ -52,8 +52,17 @@ Tagging and signing should be left to 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
-archive.  dgit push does a
-.BR "debian/rules clean" .
+archive.  (For a format `3.0 (quilt)' source package, dgit push
+may also have to make a commit on your current branch to contain
+quilt metadata.  It will do this automatically.)
+
+.B dgit quilt-fixup
+looks to see if there is quilt patch metadata left over by dpkg-source
+-b, and if so makes a git commit of it.  This is normally done
+automatically by dgit push.  dgit quilt-fixup takes no additional
+arguments.  Note that it will only process a patch generated by
+dpkg-source for the most recent version (according to the
+debia/changelog).
 .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
@@ -95,12 +104,12 @@ working branches
 If last upload was not made with git, a different approach is required
 to start using dgit.  First, do
 .B dgit fetch
-(or clone) obtain a git history representation of what's in the
+(or clone) to obtain a git history representation of what's in the
 archive and record it in the
 .BI remotes/dgit/ suite
-tracking branch.  Then construct somehow, using your other git history
+tracking branch.  Then somehow, using your other git history
 plus appropriate diffs and cherry picks from the dgit remote tracking
-branch, a git commit whose tree corresponds to the tree to use for the
+branch, construct a git commit whose tree corresponds to the tree to use for the
 next upload.  If that commit-to-be-uploaded is not a descendant of the
 dig remote tracking branch, check it out and say
 .BR "git merge -s ours remotes/dgit/" \fIsuite\fR;
@@ -178,7 +187,9 @@ represented in the single Debian patch.
 
 Secondly, you can regard your quiltish patch stack in the archive as
 primary.  You will have to use other tools besides dgit to import and
-export this patch stack.  See also the BUGS section.
+export this patch stack.  For `3.0 (quilt)' packages, dgit has to do
+more work to work around quilt braindamage.  See also the BUGS
+section.  We recommend against the use of `3.0 (quilt)'.
 .SH OPTIONS
 .TP
 .BR --dry-run | -n
@@ -232,10 +243,21 @@ 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 that
+we guess
+.B dpkg
+or use the value of this option.
 .TP
-.BI --clean-command= "cmd arg arg"
-dgit push needs to clean the tree to make sure the 
+.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 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
@@ -247,10 +269,12 @@ on the dgit command line.
 .TP
 .BI dgit.default.distro
 .TP
-.BI dgit.default.username
+.BI dgit-distro. distro .username
 .TP
 .BI dgit-distro. distro .git-url
 .TP
+.BI dgit-distro. distro .git-user
+.TP
 .BI dgit-distro. distro .git-host
 .TP
 .BI dgit-distro. distro .git-proto
@@ -269,6 +293,12 @@ on the dgit command line.
 .TP
 .BI dgit-distro. distro .archive-query-default-component
 .TP
+.BI dgit-distro. distro .sshdakls-user
+.TP
+.BI dgit-distro. distro .sshdakls-host
+.TP
+.BI dgit-distro. distro .sshdakls-dir
+.TP
 .BI dgit-distro. distro .ssh
 .TP
 .BR dgit.default. *
@@ -285,11 +315,15 @@ to an unavailable commit).
 
 The method of canonicalising suite names is bizarre.  See the
 .B --existing-package
-option for one of the implication.s
+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.
+
 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.
@@ -319,6 +353,15 @@ the .orig.tar.gz could be transported via the git repo as git tags.
 Doing this is made more complicated by the possibility of a `3.0
 (quilt)' package with multiple .orig tarballs.
 
+`3.0 (quilt)' packages have an additional difficulty: if these are
+edited in the most normal way, and then fed to dpkg-buildpackage,
+dpkg-source will add extra quilt patch metadata to the source tree
+during the source package build.  This extra metadata is then of
+course not included in the git history.  So dgit push needs to commit
+it for you, to make sure that the git history and archive contents are
+identical.  That this is necessary is a bug in the `3.0 (quilt)'
+format.
+
 The error messages are often unhelpfully terse and tend to refer to
 line numbers in dgit.