dgit: --trust-changelog: Document

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

1 files changed, 26 insertions, 21 deletions

diff --git a/dgit.1 b/dgit.1
index f03f734..ba886a6 100644
--- a/dgit.1
+++ b/dgit.1
@@ -707,7 +707,7 @@ combination can fail if the untracked files are under
 .BR --ignore-dirty
 Deprecated alias for --include-dirty.
 .TP
-.BR --overwrite [=\fIprevious-version\fR]
+.BR --trust-changelog " | " --overwrite =\fIprevious-version\fR
 Declare that your HEAD really does contain
 all the (wanted) changes
 from all versions listed in its changelog;
@@ -718,40 +718,41 @@ your git branch is not a descendant
 of the version in the archive
 according to the git revision history.
 
-It is safer not to specify
-.IR previous-version ,
-and usually it's not needed.
-Just say
-.BR \-\-overwrite ,
-unless you know what you are doing.
+It is safer to specify
+.BR \-\-trust-changelog ,
+than
+.BR \-\-overwrite= \fIprevious-version\fR,
+and usually the latter is not needed.
 
-This option is useful if you are the maintainer, and you have
+.B --trust-changelog
+is useful if you are the maintainer, and you have
 incorporated NMU changes into your own git workflow in a way that
 doesn't make your branch a fast forward from the NMU.
 It can also be useful when there was an upload made without dgit
 since the most recent upload made with dgit.
 
-This option is also usually necessary
+It is also usually necessary
 the first time a package is pushed with dgit push
 to a particular suite.
 See
 .BR dgit-maint- \fI*\fR (7) .
 
-If
-.I previous-version
-is not
-specified, dgit will check that the version in the archive is
+With
+.BR \-\-trust-changelog
+dgit will check that the version in the archive is
 mentioned in your debian/changelog.
 (This will avoid losing
-changes, even with
-.BR --overwrite ,
+changes,
 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
+With
+.BI \-\-overwrite= previous-version
+that version ought to be the version currently in the archive,
+and it will be unconditionally overwritten,
+regardless of what's in the changelog.
+
+These options
 will, if necessary, 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
@@ -763,6 +764,10 @@ implying a split between the dgit view and the
 maintainer view, the pseudo-merge will appear only in the dgit view;
 .B --split-view=always
 can be used to force that behaviour, e.g. in other quilt modes.)
+
+.B \-\-overwrite
+without a version number is an obsolete way of specifying
+.BR \-\-trust-changelog .
 .TP
 .BR \-\-delayed =\fIdays\fR
 Upload to a DELAYED queue.
@@ -858,12 +863,12 @@ When split view is in operation,
 this also prevents the construction by dgit of a pseudomerge
 to make the dgit view fast forwarding.
 Normally only one of
---overwrite (which creates a suitable pseudomerge)
+\-\-trust-changelog (which creates a suitable pseudomerge)
 and
 --deliberately-not-fast-forward
 (which suppresses the pseudomerge and the fast forward checks)
 should be needed;
---overwrite is usually better.
+\-\-trust-changelog is usually better.
 .TP
 .BR --deliberately-include-questionable-history
 Declare that you are deliberately including, in the git history of