a bug

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index f949d074a764012754788ef728b4059f83ef14fe..64a03cfd6bc291c128a66b93636d4a41e2c289a2 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -115,6 +115,10 @@ 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 -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).
@@ -135,6 +139,16 @@ debsign.  Use repeatedly if multiple additional options are required.
 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.
+.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 that
+.B dpkg
+exists in the target suite.  If it doesn't, you can use this option to
+specify a package which does.  If the suite is empty, bad luck.
 .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
@@ -166,19 +180,14 @@ on the dgit command line.
 .TP
 .BI dgit-distro. distro .archive-query
 .TP
+.BI dgit-distro. distro .archive-query-default-component
+.TP
 .BI dgit-distro. distro .ssh
 .TP
 .BR dgit.default. *
 for each
 .BR dgit-distro. \fIdistro\fR . *
 .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.
-
 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.
@@ -187,7 +196,9 @@ 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).
 
-dgit cannot currently introduce a package into a suite.
+The method of canonicalising suite names is bizarre.  See the
+.B --existing-package
+option for one of the implication.s
 
 dgit push should perhaps do `git push origin', or something similar,
 by default.
@@ -211,6 +222,9 @@ branch back into a rebasing patch stack, and a `force' option to dgit
 push (perhaps enabled automatically by a note left by rebase-prep)
 which will make the required pseudo-merge.
 
+If the dgit push fails halfway through, it should be restartable and
+idempotent.  However this is not true for the git tag operation.
+
 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.
 Doing this is made more complicated by the possibility of a `3.0
@@ -221,5 +235,10 @@ line numbers in dgit.
 
 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.
+
 --dry-run often does not work with fetch, even though this is a
 logically plausible request.  (It fails, instead.)