dgit-maint-merge(7): Create an empty branch for upstream source

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

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index b0f395d926e3952c9223dcb32cb0f94e8d0140bf..995fe8b7e28b759aab09102ff98b297c98796607 100644 (file)
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -40,10 +40,7 @@ This workflow is less suitable for some packages.
 When the Debian delta contains multiple pieces which interact,
 or which you aren't going to be able to upstream soon,
 it might be preferable to
-maintain the delta as a rebasing patch series,
-to facilitate
-reviewing/upstreaming/dropping
-individual pieces.
+maintain the delta as a rebasing patch series.
 For such a workflow see for example
 dgit-maint-gbp(7).
 
@@ -151,12 +148,23 @@ Now create I<debian/gbp.conf>:
 
 =back
 
-Then we can import the upstream version:
+gbp-import-orig(1) requires a pre-existing upstream branch:
 
 =over 4
 
     % git add debian/gbp.conf && git commit -m "create gbp.conf"
-    % gbp import-orig ../foo_1.2.2.orig.tar.xz
+    % 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
 
@@ -208,9 +216,14 @@ Then make new upstream tags available:
 
 =back
 
+=for dgit-test dpkg-source-ignores begin
+
 Now you simply need to ensure that your git HEAD is dgit-compatible,
-i.e., it is exactly what you would get if you ran B<dpkg-buildpackage
--i\.git/ -I.git -S> and then unpacked the resultant source package.
+i.e., it is exactly what you would get if you ran
+B<dpkg-buildpackage -i'(?:^|/)\.git(?:/|$)' -I.git -S>
+and then unpacked the resultant source package.
+
+=for dgit-test dpkg-source-ignores end
 
 To achieve this, you might need to delete
 I<debian/source/local-options>.  One way to have dgit check your
@@ -255,17 +268,16 @@ first upload of upstream version 1.2.3, you could use:
 
 =over 4
 
-    % git clone https://git.dgit.debian.org/
+    % git clone https://git.dgit.debian.org/foo
     % cd foo
     % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
 
 =back
 
-See dgit-maint-merge(7) for more information.
-(If you have dgit, use dgit clone foo,
-rather than plain git clone.)
+(If you have dgit, use `dgit clone foo`,
+rather than plain `git clone`.)
 
-A single combined diff, representating all the changes, follows.
+A single combined diff, containing all the changes, follows.
 
 =back