Overwrite: Document --overwrite=VERSION

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index d3f37029679076514a426fa6900f1c7f9661621f..039ee81722d12439f9d66036853973267af6ea29 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -127,9 +127,8 @@ Constructs the source package, uses
 .B  sbuild
 to do a binary build, and uses mergechanges to merge the source and
 binary changes files.  Options and arguments after sbuild will be
-passed on to sbuild.  Changes files matching
-.IB package _ version _*.changes
-in the parent directory will be removed; the output is left in
+passed on to sbuild.
+The output is left in
 .IR package \fB_\fR version \fB_multi.changes\fR.
 
 Tagging, signing and actually uploading should be left to dgit push.
@@ -331,6 +330,28 @@ This can be useful with build, if you plan to commit later.  (dgit
 push will still ensure that the .dsc you upload and the git tree
 you push are identical, so this option won't make broken pushes.)
 .TP
+.BI --overwrite= previous-version
+Declare that even though your git branch is not a descendant of
+.IR previous-version
+according to the revision history, in fact, it really does contain
+all the (wanted) changes from that version.
+.I previous-version
+ought to be the version currently in the archive.
+
+dgit push will make a
+pseudo-merge (that is, something that looks like the result
+of git merge -s ours) to stitch the archive's version into your own
+git history, so that your push is a fast forward from the archive.
+
+This option is useful if you are the maintainer, and you have
+incorporated NMU changes into your own git workflow in way that
+doesn't make your branch a fast forward from the NMU.
+
+(In quilt mode
+.BR gbp ", " dpm " or " unpatched ,
+implying a split between the dgit view and the
+maintainer view, the pseudo-merge will appear only in the dgit view.)
+.TP
 .BI --deliberately- something
 Declare that you are deliberately doing
 .IR something .
@@ -514,8 +535,7 @@ How to set this up is not yet documented.
 .BI -C changesfile
 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 - or,
-if there is a _multi.changes file, dgit uses that.
+filename suggests it is for the right package and version.
 
 If the specified
 .I changesfile
@@ -621,14 +641,17 @@ archive and record it in the
 tracking branch.  Then somehow, using your other git history
 plus appropriate diffs and cherry picks from the dgit remote tracking
 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
-dgit remote tracking branch, check it out and say
-.BR "git merge -s ours remotes/dgit/dgit/" \fIsuite\fR;
-that tells git that we are deliberately throwing away any differences
+next upload. 
+
 between what's in the archive and what you intend to upload.
 Then run
 .BR "dgit push"
 to actually upload the result.
+
+If the commit-to-be-uploaded is not a descendant of the
+dgit remote tracking branch, you will need to pass
+.B --overwrite
+to dgit.
 .SH CONFIGURATION
 dgit can be configured via the git config system.
 You may set keys with git-config (either in system-global or per-tree
@@ -748,6 +771,8 @@ or when pushing and
 .TP
 .BI dgit-distro. distro .archive-query-default-component
 .TP
+.BI dgit-distro. distro .dgit-tag-format
+.TP
 .BI dgit-distro. distro .ssh
 .TP
 .BI dgit-distro. distro .sshpsql-dbname