mention pristine-tar branch and pristine-tar

3 files changed, 25 insertions, 2 deletions

diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml
index 5b8326a1..d0687e97 100644
--- a/docs/chapters/building.sgml
+++ b/docs/chapters/building.sgml
@@ -16,7 +16,14 @@
     one by looking at the tag matching the upstream version, if no tag can be
     found it uses the tip of the current <option>upstream-branch</option>. Any
     other treeish object to create the upstream tarball from can be given with
-    the <option>--upstream-branch</option> option.</para>
+    the <option>--upstream-branch</option> option.
+    </para><para>
+    If you want to recreate the original tarball using the additional
+    information from the <option>pristine-tar branch</option> you have to
+    specify the <option>--pristine-tar</option> option. This will make sure the
+    upstream tarball matches exactly the one imported. Using this option is the
+    recommended way of recreating the upstream tarball.
+    </para>
     <para>Once you're satisfied with the build and want to do a release you commit all
     your changes and issue:</para>
 <screen>
diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
index 6ba388f3..521cc2f9 100644
--- a/docs/chapters/import.sgml
+++ b/docs/chapters/import.sgml
@@ -17,6 +17,11 @@
     <option>debian-branch</option> options in the configuration file.
     </para>
     <para>
+    If you want to be able to exactly recreate the original tarball
+    (orig.tar.gz) from &git; you should also specify the
+    <option>--pristine-tar</option> option.  This is recommended.
+    </para>
+    <para>
     If you want to import further versions you can change into your shiny new
     &git; repository and just continue with the same command:
     <screen>
@@ -65,6 +70,9 @@ by version number.
     the changes from the <option>upstream-branch</option> later.
     </para>
     <para>
+    If you want to be able to exactly recreate the original tarball
+    (orig.tar.gz) from &git; you should also specify the
+    <option>--pristine-tar</option> option.  This is recommended.
     </para>
     </sect1>
 
diff --git a/docs/chapters/intro.sgml b/docs/chapters/intro.sgml
index 36c4d2bd..8d757dfb 100644
--- a/docs/chapters/intro.sgml
+++ b/docs/chapters/intro.sgml
@@ -46,7 +46,15 @@
 	branch name used in the &git; repository is
 	<emphasis>upstream</emphasis>) holds the upstream releases. This can
 	either be a branch you import to or a branch of an upstream repository
-	you pull from.</para></listitem></itemizedlist> <para>You're completely
+	you pull from.</para></listitem>
+	<listitem><para> The <option>pristine-tar branch</option> (the default
+	branch name used in the &git; repository is
+	<emphasis>pristine-tar</emphasis>) holds the necessary additional
+	information to recreate the original tarball from the
+	<option>upstream-branch</option>. In order to use this feature you need
+	to install the &pristine-tar; package.
+	</itemizedlist>
+	<para>You're completely
 	free to pick any repository layout and the branch names above are only
 	&git-buildpackage;'s defaults. They can be changed at any point in time
 	and you can work with an arbitrary number of branches.