From 99b7b3246b32cde43dca421571c06f42e00c1baf Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Wed, 27 Jun 2018 18:22:35 +0100 Subject: [PATCH] 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 --- debian/changelog | 4 ++++ dgit.1 | 22 +++++++++++++++------- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/debian/changelog b/debian/changelog index 4d05abe3..ad5e0fe9 100644 --- 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 f15fecf9..cbf0cde5 100644 --- 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 -- 2.30.2