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 27c97aa310b5249f2d2c9e09f6552a0ec6eab736..373fb2f7aa335456d09aee970e4d4f05b4972021 100644 (file)
--- a/dgit-maint-debrebase.7.pod
+++ b/dgit-maint-debrebase.7.pod
@@ -171,64 +171,66 @@ 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
 
     [DEFAULT]
     upstream-branch = upstream
     debian-branch = master
-    upstream-tag = %(version)s
+    upstream-tag = upstream/%(version)s
 
     sign-tags = True
     pristine-tar = False
     pristine-tar-commit = False
 
     [import-orig]
-    merge-mode = merge
+    merge = False
 
 =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-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
 
@@ -353,7 +355,7 @@ release, and importing that release using git-debrebase(1).
 
 =over 4
 
-    % git fetch --all --tags
+    % git fetch --tags upstream
 
 =back
 
@@ -372,7 +374,7 @@ Then, either
 
 =over 4
 
-    % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz
+    % gbp import-orig ../foo_1.2.3.orig.tar.xz
 
 =back
 
@@ -380,7 +382,7 @@ or if you have a working watch file
 
 =over 4
 
-    % gbp import-orig --no-merge --uscan
+    % gbp import-orig --uscan
 
 =back
 
@@ -392,6 +394,8 @@ or if you have a working watch file
 
 =back
 
+replacing I<1.2.3> with I<upstream/1.2.3> if you imported a tarball.
+
 This invocation of git-debrebase(1) involves a git rebase.  You may
 need to resolve conflicts if the Debian delta queue does not apply
 cleanly to the new upstream source.