docs changes

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index a226350cf7940b82060b79b19d5d36946ab576a7..d4ce17693eb93a2b08a9c9da92538c545bae32db 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
 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).
 .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.
 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
 .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


@@ -182,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).
 
 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.
 
 dgit push should perhaps do `git push origin', or something similar,
 by default.


@@ -206,6 +222,11 @@ 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.
 
 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.
+Also, it would be good to check that the proposed signing key is
+available before starting work.
+

 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
 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