mention pristine-tar branch and pristine-tar

diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml
index 5b8326a..d0687e9 100644 (file)
--- 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 6ba388f..521cc2f 100644 (file)
--- 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 36c4d2b..8d757df 100644 (file)
--- 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.

diff --git a/docs/common.ent b/docs/common.ent
index a7fb811..3ff5716 100644 (file)
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -23,6 +23,7 @@
   <!ENTITY svn-buildpackage "<productname>svn-buildpackage</productname>">
   <!ENTITY gpg                "<productname>GPG</productname>">
   <!ENTITY dpkg-buildpackage "<productname>Dpkg-buildpackage</productname>">
+  <!ENTITY pristine-tar "<productname>pristine-tar</productname>">
   <!ENTITY lintian     "<productname>lintian</productname>">
   <!ENTITY gnu         "<acronym>GNU</acronym>">
   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">