dgit(1): Cover more cases of --overwrite and --deliberately

[dgit.git] / dgit-maint-debrebase.7.pod

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index 6ffa2301f8adc35cbf1b95605003ae5f11320021..4a0b5a52a3fec3b415f31320af91eacb8788dc9a 100644 (file)
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -134,6 +134,32 @@ using git-diff(1) to compare the imported tarball to the release tag.
 
 =back
 
+=head3 Using untagged upstream commits
+
+=over 4
+
+Sometimes upstream does not tag their releases, or you want to package
+an unreleased git snapshot.  In such a case you can create your own
+upstream release tag, of the form B<upstream/>I<ver>, where I<ver> is
+the upstream version you plan to put in I<debian/changelog>.  The
+B<upstream/> prefix ensures that your tag will not clash with any tags
+upstream later creates.
+
+For example, suppose that the latest upstream release is 1.2.2 and you
+want to package git commit ab34c21 which was made on 2013-12-11.  A
+common convention is to use the upstream version number
+1.2.2+git20131211.ab34c21 and so you could use
+
+=over 4
+
+    % git tag -s upstream/1.2.2+git20131211.ab34c21 ab34c21
+
+=back
+
+to obtain a release tag, and then proceed as above.
+
+=back
+
 =head2 When upstream releases only tarballs
 
 Because we want to work in git, we need a virtual upstream branch with
@@ -327,10 +353,14 @@ release, and importing that release using git-debrebase(1).
 
 =over 4
 
-    % git remote update
+    % git fetch --tags upstream
 
 =back
 
+If you want to package an untagged upstream commit (because upstream
+does not tag releases or because you want to package an upstream
+development snapshot), see "Using untagged upstream commits" above.
+
 =head3 When upstream releases only tarballs
 
 You will need the I<debian/gbp.conf> from "When upstream releases only
@@ -375,7 +405,7 @@ release:
 
 =back
 
-Additionally pass I<--name-status> and I<--diff-filter=ADR> to see
+Also, diff with I<--name-status> and I<--diff-filter=ADR> to see
 just the list of added or removed files, which is useful to determine
 whether there are any new or deleted files that may need accounting
 for in your copyright file.