X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit-maint-merge.7.pod;h=22be1c9e2199244acf697bb747d1ed4c3fff1d43;hp=ed7cdc060fac83be63547f2f9e60c605a8a13490;hb=53391de137eb887e0807d7e0339a855c5140451a;hpb=1ea867d81b069b145a9e1b7a38c97e99e1c40e4f

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index ed7cdc06..22be1c9e 100644
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -171,12 +171,9 @@ Then we can import the upstream version:
 
 =back
 
-You are now ready to proceed as above, making commits to both the
-upstream source and the I<debian/> directory.
-
-If you want to maintain a copy of your repository on
-B<alioth.debian.org>, you should push both the origin and the upstream
-branches:
+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<alioth.debian.org>:
 
 =over 4
 
@@ -185,6 +182,9 @@ branches:
 
 =back
 
+You are now ready to proceed as above, making commits to both the
+upstream source and the I<debian/> directory.
+
 =head1 CONVERTING AN EXISTING PACKAGE
 
 This section explains how to convert an existing Debian package to
@@ -202,7 +202,16 @@ this workflow.  It should be skipped when debianising a new package.
 
 =head2 Existing git history using another workflow
 
-First, dump any existing patch queue:
+First, if you don't already have the git history locally, clone it,
+and obtain the corresponding orig.tar from the archive:
+
+=over 4
+
+    % git clone git.debian.org:collab-maint/foo
+    % cd foo
+    % origtargz
+
+Now dump any existing patch queue:
 
 =over 4
 
@@ -232,7 +241,12 @@ To achieve this, you might need to delete
 I<debian/source/local-options>.  One way to have dgit check your
 progress is to run B<dgit build-source>.
 
-The first dgit push will require I<--overwrite>.
+The first dgit push will require I<--overwrite>.  If this is the first
+ever dgit push of the package, consider passing
+I<--deliberately-not-fast-forward> instead of I<--overwrite>.  This
+avoids introducing a new origin commit into your git history.  (This
+origin commit would represent the most recent non-dgit upload of the
+package, but this should already be represented in your git history.)
 
 =head1 SOURCE PACKAGE CONFIGURATION
 
@@ -322,7 +336,9 @@ to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
 =head3 When upstream releases only tarballs
 
 You will need the I<debian/gbp.conf> from "When upstream releases only
-tarballs", above.
+tarballs", above.  You will also need your upstream branch.  Above, we
+pushed this to B<alioth.debian.org>.  You will need to clone or fetch
+from there, instead of relying on B<dgit clone>/B<dgit fetch> alone.
 
 Then, either