dgit-maint-debrebase(7): Import tarball before committing gbp.conf

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

diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod
index 77b4eca0ef8fd27e52b8713feb1f5fc4ab6597c8..373fb2f7aa335456d09aee970e4d4f05b4972021 100644 (file)
--- 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