docs: improve docs on using upstream's git repo

The documentation on using upstream's git directly instead of tarballs
was very terse. Add a step by step guide on how to get started and
how to update to new upstream versions.

1 files changed, 49 insertions, 6 deletions

diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
index 2522b8be..2c05e5dd 100644
--- a/docs/chapters/import.sgml
+++ b/docs/chapters/import.sgml
@@ -183,7 +183,7 @@ EOF
     <sect1 id="gbp.import.upstream-git">
     <title>When upstream uses GIT</title>
     <para>
-      If upstream already uses git for packaging there are several ways to handle packaging. Two will
+      If upstream already uses git for packaging there are several ways to handle packaging. Two of them will
       be described in a bit detail here:
     </para>
 
@@ -194,9 +194,9 @@ EOF
 	</para>
 
 	<para>
-	  &gbp-buildpackage; will by default create an upstream tarball for you. By default it will
-	  be created from the tag name given by the <option>--git-upstream-tag</option> option.
-	  You can customize it's value via the <option>upstream-tag</option> configuration variable.
+	  In order to help &gbp-buildpackage; to find upstream tags you need to specify the format
+	  using the <option>--git-upstream-tag</option> comand line option or the the <option>upstream-tag</option>
+	  configuration variable.
 	</para>
 
 	<para>
@@ -211,9 +211,52 @@ upstream-tag = v%(version)s
 	  <replaceable>version</replaceable> will be replaced with the upstream version number as read from
 	  <filename>debian/changelog</filename>.
 	</para>
-	<para>If you're using &pristine-tar; you can make &gbp-buildpackage commit the tarball back to the
-	  pristine-tar branch by using the <option>--git-pristine-tar-commit</option> option.
+	<para>If you're using &pristine-tar; you can make &gbp-buildpackage commit the generated tarball back to the
+	  pristine-tar branch by using the <option>--git-pristine-tar-commit</option> option. This will make sure
+	  others building your package can regenerate the tarball you generated for building the Debian pacakge.
 	</para>
+
+	<sect3>
+	  <title>Step by step</title>
+	<para>To not make any assumptions about &gbp;'s configuration the following steps have all options given
+	  in its long versions on the command line . You can add these
+	  to &gbp.conf; to save lots of typing.
+	</para>
+
+	<para>First we clone the upstream repository. To avoid any dis ambiguities between the Debian packaging repository
+	  and the upstream repository we name the upstream repository <replaceable>ustream</replaceable> instead of the
+	  default <replaceable>origin</replaceable>.
+	  <screen>
+	    git clone --no-checkout -o upstream git://git.example.com/libgbp.git
+	    cd libgbp
+	    git checkout -b debian/sid v1.0
+	  </screen>
+	  The above makes sure we have <replaceable>debian/sid</replaceable> for the Debian packaging. We didn't create
+	  any <replaceable>upstream/*</replaceable> branches, they're not needed for the packaging and only need to be
+	  kept up to date. After adding the Debian packaging we build the package. This assumes you're using &pristine-tar;
+	  and upstream uses a version number format as described above:
+	  <screen>
+	    gbp buildpackage --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid
+	  </screen>
+	  When updating to a new upstream version we simply fetch from upstream and merge in the new tag. Afterwards we
+	  update the changelog and build the package:
+	  <screen>
+	    git fetch upstream
+	    git merge v1.1
+	    gbp dch --debian-branch=debian/sid --snapshot --auto debian/
+	    gbp buildpackage --git-ignore-new --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s'
+	  </screen>
+	  Note that the above &gbp-dch; call makes sure we only pickup changes in the <filename>debian/</filename>
+	  directory. Since we told it to build a snapshot changelog entry and we didn't commit the changelog yet
+	  we need to tell &gbp-buildpackage; that the working directory is unclean via the <option>--git-ignore-new</option>.
+	  Once everything looks good commit the changelog and build a release version:
+	  <screen>
+	    gbp dch --release --auto --git-debian-branch=debian/sid
+	    git commit -m"Release 1.1-1" debian/changelog
+	    gbp buildpackage --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid
+	  </screen>
+	  If you want to share you're repository with others you can use &gbp-create-remote-repo; and &gbp-pull; as usual.
+	</sect3>
       </sect2>
 
       <sect2 id="gbp.import.upstream.git.tarball">