X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit-maint-merge.7.pod;h=245be4c937a744cffd16bdc7a8f709b056cd1ce3;hp=03ccdfe84acb0e2e4310f455d5307293d7e8bd26;hb=d4f8df7adccd9ed9a0dd1cd1837ed7782557a828;hpb=3bdf06f4ea6d3735c73c12903e3ac7ce8447f61a

diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod
index 03ccdfe8..245be4c9 100644
--- a/dgit-maint-merge.7.pod
+++ b/dgit-maint-merge.7.pod
@@ -16,9 +16,6 @@ Git histories should be the non-linear histories produced by
 git-merge(1), preserving all information about divergent development
 that was later brought together.
 
-If you prefer linear histories, see dgit-maint-gbp(7)
-for a workflow based on git-buildpackage, or roll your own.
-
 =item
 
 Maintaining convenient and powerful git workflows takes priority over
@@ -53,6 +50,10 @@ compress orig tarballs:
 
 =head1 INITIAL DEBIANISATION
 
+This section explains how to start using this workflow with a new
+package.  It should be skipped when converting an existing package to
+this workflow.
+
 =head2 When upstream tags releases in git
 
 Suppose that the latest stable upstream release is 1.2.2, and this has
@@ -175,6 +176,50 @@ branches:
 
 =back
 
+=head1 CONVERTING AN EXISTING PACKAGE
+
+This section explains how to convert an existing Debian package to
+this workflow.  It should be skipped when debianising a new package.
+
+=head2 No existing git history
+
+=over 4
+
+    % dgit clone foo
+    % cd foo
+    % git remote add -f upstream https://some.upstream/foo.git
+
+=back
+
+=head2 Existing git history using another workflow
+
+First, dump any existing patch queue:
+
+=over 4
+
+    % git rm -rf debian/patches
+    % git commit -m "drop existing quilt patch queue"
+
+=back
+
+Then make new upstream tags available:
+
+=over 4
+
+    % git remote add -f upstream https://some.upstream/foo.git
+
+=back
+
+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.
+
+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>.
+
 =head1 SOURCE PACKAGE CONFIGURATION
 
 =head2 debian/source/options
@@ -193,7 +238,7 @@ source:
 You don't need to create this file if you are using the version 1.0
 source package format.
 
-=head2 Sample text for README.source
+=head2 Sample text for debian/source/patch-header
 
 It is a good idea to explain how a user can obtain a break down of the
 changes to the upstream source:
@@ -218,6 +263,10 @@ See dgit(1), dgit(7) and dgit-maint-merge(7) for more information.
 
 =back
 
+Alternatively, this text could be added to README.source. However,
+this might distract from more important information present in the
+latter file.
+
 =head1 BUILDING AND UPLOADING
 
 Use B<dgit build>, B<dgit sbuild>, B<dgit build-source>, and B<dgit
@@ -264,7 +313,7 @@ Once you're satisfied with what will be merged, update your package:
 
 =over 4
 
-    % git archive ../foo_1.2.3.orig.tar.xz 1.2.3
+    % git archive -o ../foo_1.2.3.orig.tar.xz 1.2.3
     % git merge 1.2.3
     % dch -v1.2.3-1 New upstream release.
     % git add debian/changelog && git commit -m changelog
@@ -278,7 +327,10 @@ Again, if you are using the version 1.0 source package format, replace
 
 =head2 When upstream releases only tarballs
 
-Either
+You will need the I<debian/gbp.conf> from "When upstream releases only
+tarballs", above.
+
+Then, either
 
 =over 4