Ian Jackson writes ("Re: Bug#902534: dgit: needs a better integration story
with patches-unapplied maintainer trees"):
> I think maybe the fact that I am writing this all here suggests we
> need better wording in the --overwrite section of dgit(1).
How about this ?
--overwrite[=previous-version]
Declare that your HEAD really does contain all the (wanted)
changes from all versions listed in its changelog; or, all
(wanted) changes from previous-version. This promise is needed
when your git branch is not a descendant of the version in the
archive 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 doesn't make your branch a fast forward from the NMU.
This option is also usually necessary the first time a package
is pushed with dgit push to a particular suite. See dgit-
maint-*(7).
If 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, even with --overwrite, unless
someone committed to git a finalised changelog entry, and then
made later changes to that version.) If previous-version is
specified, it ought to be the version currently in the archive.
[etc]
>From 99b7b3246b32cde43dca421571c06f42e00c1baf Mon Sep 17 00:00:00 2001
From: Ian Jackson <[email protected]>
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 <[email protected]>
---
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.11.0
