construct import commits differently (merge separate from contents)

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index 4fd00c0622983117ecf4df3114c2dbc4d29d5d67..9a9f32e2730633b64eca7949df7aa4ccbc72917e 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -84,8 +84,9 @@ branch) whose tree is identical to the unpacked source upload.
 
 Uploads not made by dgit are represented in git by commits which are
 synthesised by dgit.  The tree of each such commit corresponds to the
-unpacked source; the single parent is the last known upload - that is,
-the contents of the dgit/suite branch.
+unpacked source; there is an origin commit with the contents, and a
+psuedo-merge from last known upload - that is, from the contents of
+the dgit/suite branch.
 
 dgit expects repos that it works with to have a
 .B dgit
@@ -139,6 +140,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
@@ -186,7 +197,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.
@@ -210,6 +223,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.
 
+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