dgit(1): Better description of --overwrite.

In particular, be clear that --overwrite (without previous-version) is
quite a weak promise: that the version you are uploading contains
everything in your changelog.  It won't overwrite willy-nilly.

Somewhat apropos of discussion in #902534.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/debian/changelog b/debian/changelog
index 4d05abe3b266734cfd41f3aeecb85c6fac75eb0b..ad5e0fe95a35fc10f8b601aa4827a83a2782ca8d 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,5 +1,9 @@
 dgit (5.4~) unstable; urgency=medium
 
+  Improvements:
+  * dgit(1): Better description of --overwrite.  Somewhat
+    apropos of discussion in #902534.
+
   Bugfixes:
   * Fix bug ref to #865444 in previous changelog entry.
 

diff --git a/dgit.1 b/dgit.1
index f15fecf964448a3730e7ad52d975e5d40199af0b..cbf0cde5ec042476b6c20f1341abb38cadd241cf 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -514,11 +514,15 @@ 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
 .BR --overwrite [=\fIprevious-version\fR]
-Declare that even though your git branch may not be a descendant
+Declare that your HEAD really does contain
+all the (wanted) changes
+from all versions listed in its changelog;
+or, all (wanted) changes from
+.IR previous-version .
+This promise is needed when
+your git branch is not a descendant
 of the version in the archive
-according to the revision history,
-it really does contain
-all the (wanted) changes from that version.
+according to the git revision history.
 
 This option is useful if you are the maintainer, and you have
 incorporated NMU changes into your own git workflow in a way that
@@ -530,15 +534,19 @@ to a particular suite.
 See
 .BR dgit-maint- \fI*\fR (7) .
 
-.I previous-version
-ought to be the version currently in the archive.  If
+If
 .I previous-version
 is not
 specified, dgit will check that the version in the archive is
 mentioned in your debian/changelog.
 (This will avoid losing
-changes unless someone committed to git a finalised changelog
+changes, even with
+.BR --overwrite ,
+unless someone committed to git a finalised changelog
 entry, and then made later changes to that version.)
+If
+.IR previous-version
+is specified, it ought to be the version currently in the archive.
 
 dgit push --overwrite
 will, if necessary, make a