From bc83ffe7319cab9f1b76b47de9426340836872fe Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Thu, 25 Jul 2019 07:03:36 +0100
Subject: [PATCH] dgit-maint-debrebase(7): Import tarball before committing
 gbp.conf

The workflow given previously fails to produce a history that can work
with git-debrebase, because it has the first commit introducing
debian/ be an ancestor of the first import of the upstream source.

This is the final part of #932954.

Closes: #932954.
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
---
 dgit-maint-debrebase.7.pod | 64 ++++++++++++++++++++------------------
 1 file changed, 33 insertions(+), 31 deletions(-)

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index 77b4eca0..373fb2f7 100644
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -171,10 +171,37 @@ begin
     % mkdir foo
     % cd foo
     % git init
+    % git checkout -b upstream
+    % gbp import-orig \
+        --upstream-branch=upstream --debian-branch=master \
+        --upstream-tag='upstream/%(version)s' \
+        --sign-tags --no-pristine-tar \
+        ../foo_1.2.2.orig.tar.xz
+    % git branch -f upstream
 
 =back
 
-Now create I<debian/gbp.conf>:
+This should leave you on the master branch.  Next, our upstream branch
+cannot be pushed to B<dgit-repos>, but since we will need it whenever
+we import a new upstream version, we must push it somewhere.  The
+usual choice is B<salsa.debian.org>:
+
+=over 4
+
+    % git remote add -f origin salsa.debian.org:Debian/foo.git
+    % git push --follow-tags -u origin master upstream
+
+=back
+
+You are now ready to proceed as above, making commits to the
+I<debian/> directory and to the upstream source.  As above, for
+technical reasons, B<it is essential that your first commit introduces
+the debian/ directory containing at least one file, and does nothing
+else.>  In other words, make a commit introducing I<debian/> before
+patching the upstream source.
+
+A convenient way to ensure this requirement is satisfied is to start
+by creating I<debian/gbp.conf>:
 
 =over 4
 
@@ -192,43 +219,18 @@ Now create I<debian/gbp.conf>:
 
 =back
 
-gbp-import-orig(1) requires a pre-existing upstream branch:
+and commit that:
 
 =over 4
 
     % git add debian/gbp.conf && git commit -m "create gbp.conf"
-    % git checkout --orphan upstream
-    % git rm -rf .
-    % git commit --allow-empty -m "initial, empty branch for upstream source"
-    % git checkout -f master
 
 =back
 
-Then we can import the upstream version:
-
-=over 4
-
-    % gbp import-orig --merge --merge-mode=replace ../foo_1.2.2.orig.tar.xz
-
-=back
-
-Our upstream branch cannot be pushed to B<dgit-repos>, but since we
-will need it whenever we import a new upstream version, we must push
-it somewhere.  The usual choice is B<salsa.debian.org>:
-
-=over 4
-
-    % git remote add -f origin salsa.debian.org:Debian/foo.git
-    % git push --follow-tags -u origin master upstream
-
-=back
-
-You are now ready to proceed as above, making commits to the
-I<debian/> directory and to the upstream source.  As above, for
-technical reasons, B<it is essential that your first commit introduces
-the debian/ directory containing at least one file, and does nothing
-else.>  In other words, make a commit introducing I<debian/> before
-patching the upstream source.
+Note that we couldn't create I<debian/gbp.conf> before now for the
+same technical reasons which require our first commit to introduce
+I<debian/> without patching the upstream source.  That's why we had to
+pass a lot of options to our first call to gbp-import-orig(1).
 
 =head1 CONVERTING AN EXISTING PACKAGE
 
-- 
2.30.2