Documentation updates

8 files changed, 225 insertions, 123 deletions

diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml
index 8de8fd4c..4fb85fb6 100644
--- a/docs/chapters/building.sgml
+++ b/docs/chapters/building.sgml
@@ -3,19 +3,55 @@
     <para>
     In order to build a &debian; package from the &git; repository you use:
     &git-buildpackage;. During the development phase (when you're either not
-    on the <emphasis>master</emphasis>-branch or when you have uncommitted
+    on the <emphasis>debian-branch</emphasis> or when you have uncommitted
     changes in your repository) you'll usually use:
 <screen>
 &git-buildpackage; <option>--git-ignore-new</option>
 </screen>
-    Once you're satisfied with the build and want to do a relese you commit all
-    your changes and issue:
+    <para>If &git-buildpackage; doesn't find a valid upstream tarball it will create
+    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 objecto to create the upstream tarball from can be given with
+    the <option>--upstream-branch</option> option.</para>
+    <para>Once you're satisfied with the build and want to do a relese you commit all
+    your changes and issue:</para>
 <screen>
 &git-buildpackage; <option>--git-tag</option>
 </screen>
-    This will again build the debian package and tag the final result after
+    <para>This will again build the debian package and tag the final result after
     extracting the current version from the changelog. If you want &gpg; signed
     tags you can use the <option>--git-sign</option> and
-    <option>--git-keyid</option> options.
+    <option>--git-keyid</option> options. To safe typing these option can be
+    specified via the configuration files. You can futhermore change the tag
+    format used when creating tags with the <option>debian-tag</option>
+    option.</para>
+    <sect1 id="gbp.building.export">
+    <title>Using a separate build dir</title>
+    <para>Tools like &svn-buildpackage; use a separate build-area. To achieve a similar behaviour
+    with &git-buildpackage; use the <option>--export-dir</option> option:</para>
+<screen>
+&git-buildpackage; <option>--export-dir</option>=<replaceable>../build-area/</replaceable>
+</screen>
+    <para>This will export the current branch head to
+    <replaceable>../build-area/package-version</replaceable>, check out the corresponding
+    upstream tree to build the .orig.tar.gz  if necessary and build the
+    package. If you don't want to export the current branch head you can use
+    <option>--export</option> to export any treeish object, here are some
+    examples:</para>
+<screen>
+&git-buildpackage; <option>--export-dir</option>=<replaceable>../build-area</replaceable> <option>--export</option>=<replaceable>debian/0.4.3</replaceable>
+&git-buildpackage; <option>--export-dir</option>=<replaceable>../build-area</replaceable> <option>--export</option>=<replaceable>etch</replaceable>
+&git-buildpackage; <option>--export-dir</option>=<replaceable>../build-area</replaceable> <option>--export</option>=<replaceable>8caed309653d69b7ab440e3d35abc090eb4c6697</replaceable>
+</screen>
+    <para>If you want to default to build in a separate build area you can
+    specify the directory to use in the gbp.conf.
     </para>
+<programlisting>
+[git-buildpackage]
+# use a build area relative to the git repository
+build-area=../build-area
+# to use the same build area for all packages use an absolute path:
+#build-area=/home/debian-packages/build-area
+</programlisting>
+    </sect1>
 </chapter>
diff --git a/docs/chapters/cfgfile.sgml b/docs/chapters/cfgfile.sgml
index 92722133..6aa2f10d 100644
--- a/docs/chapters/cfgfile.sgml
+++ b/docs/chapters/cfgfile.sgml
@@ -1,6 +1,6 @@
 <chapter id="gbp.cfgfile">
     <title>Configuration files</title>
-    <para>Three configuration files are parsed in this order:
+    <para>Four configuration files are parsed in this order:
     <variablelist>
       <varlistentry>
       <term>/etc/git-buildpackage/gbp.conf</term>
@@ -11,16 +11,20 @@
       <listitem><para>per user configuration</para></listitem>
       </varlistentry>
       <varlistentry>
+      <term>.gbp.conf</term>
+      <listitem><para>per repository/branch configuration</para></listitem> 
+      </varlistentry> 
+      <varlistentry>
       <term>.git/gbp.conf</term>
-      <listitem><para>per working copy configuration</para></listitem> 
+      <listitem><para>per (local) repository configuration</para></listitem> 
       </varlistentry> 
     </variablelist>
-    All three have the same format. They consist of (at most) four sections, all of them are optional:
+    All four have the same format. They consist of (at most) five sections, all of them are optional:
     <variablelist>
       <varlistentry>
       <term>[DEFAULT]</term>
       <listitem><para>Options in this section apply to &git-buildpackage;,
-      &git-import-orig; and &git-import-dsc;.</para></listitem>
+      &git-import-orig;, &git-import-dsc; and &git-dch;.</para></listitem>
       </varlistentry>
       <varlistentry>
       <term>[git-buildpackage]</term>
@@ -37,6 +41,11 @@
       <listitem><para>Options in this section apply to &git-import-dsc; only and override options from the
       [DEFAULT] section.</listitem>
       </varlistentry>
+      <varlistentry>
+      <term>[git-dch]</term>
+      <listitem><para>Options in this section apply to &git-dch; only and override options from the
+      [DEFAULT] section.</listitem>
+      </varlistentry>
     </variablelist>
     The actual options in these sections are the command line options without
     the '--' prefix. So <option>--upstream-branch=</option><replaceable>dfsgfree</replaceable> would read:
@@ -44,9 +53,8 @@
 <option>upstream-branch</option>=<replaceable>dfsgfree</replaceable>
 </screen>
     in the config file. In the special case of &git-buildpackage; the stripped
-    prefix is not '--' but '--git-'.
-    Here's a full example:
-<screen>
+    prefix is not '--' but '--git-'. Here's a more complete example:
+<programlisting>
 [DEFAULT]
 # the default build command
 builder=debuild -i\.git -I.git
@@ -55,7 +63,6 @@ upstream-branch=upstream
 # the default branch for the debian patch
 debian-branch=master
 
-# Special options for git-buildpackage
 [git-buildpackage]
 upstream-branch=dfsgclean
 # Sign tags with GPG:
@@ -63,13 +70,14 @@ sign-tags = True
 # Keyid to sign tags with
 #keyid = 0xdeadbeef
 
-# Special options for git-import-orig
 [git-import-orig]
 upstream-branch=notdfsgclean
 
-# Special options for git-import-dsc
 [git-import-dsc]
 upstream-branch=notdfsgclean
-</screen>
+
+[git-dch]
+git-log=--no-merges
+</programlisting>
     </para>
 </chapter>
diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
index 13b6ae67..1bbca3f0 100644
--- a/docs/chapters/import.sgml
+++ b/docs/chapters/import.sgml
@@ -8,12 +8,13 @@
 &git-import-dsc; package_0.1-1.dsc
     </screen>
     This will create a new git repository named after the imported package, put
-    the upstream sources onto the <emphasis>upstream</emphasis> branch and the
-    debian patch on the <emphasis>master</emphasis> branch. In case of a debian
-    native package only the <emphasis>master</emphasis> branch is being used.
-    You can specify different branch names via the
+    the upstream sources onto the <option>upstream-branch</option> and the
+    debian patch on the <option>debian-branch</option>. In case of a debian
+    native package only the <option>debian-branch</option> is being used.
+    You can specify alternative branch names via the
     <option>--upstream-branch</option> and <option>--debian-branch</option>
-    options.
+    options or via the <option>upstream-branch</option> and
+    <option>debian-branch</option> options in the configuration file.
     </para>
     </sect1>
 
@@ -22,24 +23,24 @@
     <para>Change into your git repository (which can be empty), make sure it
     has all local modifications committed and run either of:
     <screen>
-&git-import-orig; /path/to/package_0.2.orig.tar.gz
-&git-import-orig; /path/to/package_0.2.tar.bz2
-&git-import-orig; /path/to/package-0.2/
+&git-import-orig; <filename>/path/to/package_0.2.orig.tar.gz</filename>
+&git-import-orig; <filename>/path/to/package_0.2.tar.bz2</filename>
+&git-import-orig; <filename>/path/to/package-0.2/</filename>
     </screen>
-    This puts the upstream souces onto the <emphasis>upstream</emphasis> branch.
-    The result of this is then merged onto the <emphasis>master</emphasis>
-    branch and a new changelog entry is created. You can again specify
+    This puts the upstream souces onto the <option>upstream-branch</option>.
+    The result of this is then merged onto the <option>debian-branch</option>
+    and a new &debian; changelog entry is created. You can again specify
     different branch names via the <option>--upstream-branch</option> and
     <option>--debian-branch</option> options. You can also filter out content
     you don't want imported:
     <screen>
-&git-import-orig; --filter='CVS/*' /path/to/package_0.2.orig.tar.gz
+&git-import-orig; <option>--filter</option>=<replaceable>'CVS/*'</replaceable> <filename>/path/to/package_0.2.orig.tar.gz</filename>
     </screen>
     </para> 
     <para>
-    If you expect a merge conflict you can delay the merge to
-    <emphasis>master</emphasis> via the <option>--no-merge</option> and pull in
-    the changes from the <emphasis>upstream</emphasis> branch any time later.
+    If you expect a merge conflict you can delay the merge to the
+    <option>debian-branch</option> via the <option>--no-merge</option> and pull in
+    the changes from the <option>upstream-branch</option> later.
     </para>
     <para>
     </para>
@@ -54,21 +55,23 @@
     <title>Upstream sources on a branch</title>
     <para>
     If the upstream sources are already on a separate branch things are pretty
-    simple. You can either rename that branch to <emphasis>upstream</emphasis>
-    with:
+    simple. You can either rename that branch to the default
+    <option>upstream-branch</option> name <emphasis>upstream</emphasis> with:
     <screen>
-mv .git/theupstream-branch .git/upstream
+&gitcmd; branch upstream theupstream-branch
+&gitcmd; branch <option>-D</option> theupstream-branch
     </screen> 
-    or you can tell &git-buildpackage; the name of the branch:
+    or you can tell &git-buildpackage; the name of the branch to use as
+    <option>upstream-branch</option>:
     <screen>
-cat &lt;&lt;EOF &gt; <filename>.git/gbp.conf</filename>
+<command>cat</command> &lt;&lt;EOF &gt; <filename>.git/gbp.conf</filename>
 [DEFAULT]
 # this is the upstream-branch:
 upstream-branch=theupstream-branch
     </screen>
-    If you use &git-import-orig; to import new upstream sources, they will
-    end up on <emphasis>theupstream-branch</emphasis> and merged to
-    <emphasis>master</emphasis>.
+    If you then use &git-import-orig; to import new upstream sources, they will
+    from now on end up on <emphasis>theupstream-branch</emphasis> and
+    merged to the <option>debian-branch</option>.
     </para>
     </sect2>
     <sect2>
@@ -88,13 +91,13 @@ upstream-branch=theupstream-branch
     assumes that this was the first commit to that repository.
     </para>
     <warning><para>There's currently no <emphasis>easy</emphasis> way to create the
-    <emphasis>upstream</emphasis> branch if you never had the upstream sources
+    <option>upstream-branch</option> if you never had the upstream sources
     as a single commit. Using &git-import-orig; on such repositories might lead
     to unexpected merge results.</para></warning>
     <para>In order to fix this you can prepend the upstream sources as a
     single commit to your tree using &git;'s <ulink
     url="http://git.or.cz/gitwiki/GraftPoint">grafts</ulink>. Afterwards you
-    can simply create a branch as explained above and &git-import-orig; should
+    can simply create a branch as explained above and &git-import-orig; will 
     work as expected.</para>
     </sect2>
     </sect1>
@@ -106,16 +109,16 @@ upstream-branch=theupstream-branch
     what if you want to start a new package? First create an empty repository:
     </para>
     <screen>
-mkdir package-0.1
-cd package-0.1
-git-init
+<command>mkdir</command> package-0.1
+<command>cd</command> package-0.1
+<command>git-init</command>
     </screen> 
-    <para>Then you import the upstream sources, branch of the
-    <emphasis>upstream</emphasis> branch and add the debian files (e.g. via dh_make):
+    <para>Then you import the upstream sources, branch off the
+    <option>upstream-branch</option> branch and add the debian files (e.g. via dh_make):
     <screen>
-&git-import-orig -u 0.1 ../package-0.1.tar.gz
-git-branch upstream
-dh_make
+&git-import-orig; <option>-u</option> <replaceable>0.1</replaceable> <filename>../package-0.1.tar.gz</filename>
+&gitcmd; branch upstream
+<command>dh_make</command>
     </screen>
     That's it, you're done.
     </sect1>
diff --git a/docs/chapters/intro.sgml b/docs/chapters/intro.sgml
index 683811e9..32e9b83b 100644
--- a/docs/chapters/intro.sgml
+++ b/docs/chapters/intro.sgml
@@ -5,48 +5,93 @@
       <ulink url="http://www.debian.org/">Debian</ulink> package build
       system with <ulink url="http://git.or.cz/">Git</ulink>.
     </para>
+    <para>
+    What can these tools do for you:
+    <itemizedlist>
+    <listitem><para>Import an existing &debian; package into &git;</para></listitem>
+    <listitem><para>Import new upstream versions, NMUs etc. with optional filters</para></listitem>
+    <listitem><para>Automatic upstream tarball generation</para></listitem>
+    <listitem><para>Maintain a consistent branch an tag naming across
+    repositires or across a team of developers</para></listitem>
+    <listitem><para>Automatically sign tags</para></listitem>
+    <listitem><para>Automatically push changes to remote repositories</para></listitem>
+    <listitem><para>Make sure you have committed all changes to the right
+    branch before releasing</para></listitem>
+    <listitem><para>Export to a clean build area before building</para></listitem>
+    <listitem><para>Automatic debian/changelog generation</para></listitem>
+    <listitem><para>Automatic generation of snapshot releases for local testing</para></listitem>
+    </itemizedlist>
+    All of this is (hopefully) being done without restricting the user to certain usage patterns.
+    </para>
 
 <sect1 id="gbp.repository">
-	<title>Repository Layout</title>
-	<para>
-	Since &git; knows about branches (and in fact handles them very well)
-	the git repository usually looks like: a so called
-	<emphasis>master</emphasis> branch (the default branch) holds your
-	current development work. Another branch called
-	<emphasis>upstream</emphasis> holds the upstream sources. Other
-	branches like <emphasis>nmu</emphasis> or
-	<emphasis>dfsg_free</emphasis> might help with certain kinds of
-	packages.  Git-Buildpackage currently only works with your local
-	git-repository, in order to publish your changes simply use
-	<command>git-push</command>.
+	<title>Repository Layout and Terminology</title>
+	<para>The only requirement on the repository layout for using
+	&git-buildpackage; and friends is, that the branch the debian work is
+	being done on is different from the branch the upstream sources are
+	being maintained on (this, of course, has no meaning for Debian native
+	packages). This is necessary to be able to build upstream tarballs and
+	to merge in new upstream versions. To distinguish these two branches
+	the following terminology <footnote><para>corresponding to the command
+	line and config file options</para></footnote> is used:
 	</para>
-</sect1> 
+	<itemizedlist>
+	<listitem><para>The <option>debian-branch</option> (the default branch
+	name used in the &git; repository is <emphasis>master</emphasis>) holds
+	your current development work.  That's the branch you usually cut your
+	releases from and the default branch new upstream releases are merged
+	onto.</para></listitem>
+	<listitem><para> The <option>upstream-branch</option> (the default
+	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
+	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.
+	For example branches like  <emphasis>nmu</emphasis>,
+	<emphasis>bpo</emphasis> or <emphasis>stable</emphasis> might
+	(temporarilly or permanent) become your <option>debian-branch</option>
+	and branches like <emphasis>dfsg_free</emphasis> or
+	<emphasis>snapshots</emphasis> might become your
+	<option>upstream-branch</option> - it doesn't matter if these branches
+	are maintend with &git-import-orig; or not.</para>
+	<para>Since Git-Buildpackage only works with local &git;-repositories
+	you have to use <command>git-push</command> in order to publish your
+	changes to remote repositories like <ulink
+	url="http://git.debian.org/">git.debian.org</ulink>, this can also be
+	automized with &git-buildpackage;'s <option>post-tag</option>
+	hook.</para>
+</sect1>
 
 <sect1 id="gbp.workflow">
     <title>Workflow</title>
     <para>
-    	A typical workflow consists of the following steps:
+    	A typical, simple workflow consists of the following steps:
     </para>
     <orderedlist>
-	<listitem><para>Import a Debian package via &git-import-dsc;. This
-	imports the &debian; Package on the master branch and the upstream
-	sources on the upstream branch.</para></listitem>
+	<listitem><para>Import a new Debian package via &git-import-dsc;. This
+	imports the &debian; Package on the <option>debian-branch</option>
+	and the upstream sources on the <option>upstream-branch</option>.</para></listitem>
 	<listitem><para>Develop, test, commit changes. During this time you can
 	always build the package with &git-buildpackage;. In case you have
 	uncommitted changes in your source tree you can use the
 	<option>--git-ignore-new</option> option.</para></listitem>
 	<listitem><para>Optionally you can create the Debian changelog entries
-	using &git-dch; and create snapshot releases for testing using the
+	using &git-dch; and create snapshot releases for testing using it's
 	<option>--snapshot</option> option.</para></listitem>
 	<listitem><para>Once satisfied you can build the final package with
-	&git-buildpackage; <option>--git-tag</option>. This
-	additionally creates a tag within &git; so you can switch back to that
-	version later at any time.</para></listitem>
-	<listitem><para>When a new upstream version is released you can import
-	this via &git-import-orig; onto the upstream branch.
-	&git-import-orig; will also try to merge the new upstream version onto
-	the master branch. After resolving any potential conflicts go back to 2.
-	</para></listitem>
+	&git-buildpackage; <option>--git-tag</option>. This additionally
+	creates a tag within &git; so you can switch back to that version later
+	at any time. The format of the tags can be specified, tags can
+	be &gpg; signed.</para></listitem>
+	<listitem><para>When a new upstream version is released and upstream
+	isn't using &git; you can import the new version via &git-import-orig;
+	onto the <option>upstream-branch</option>.  &git-import-orig; will
+	by default try to merge the new upstream version onto the
+	<option>debian-branch</option>. You can skip the merge with
+	<option>--no-merge</option>.  After resolving any potential conflicts
+	go back to the second step.  </para></listitem>
     </orderedlist>
     <para>These steps will be explaind in more details in the following sections.</para>
 </sect1>
diff --git a/docs/chapters/releases.sgml b/docs/chapters/releases.sgml
index 2ee3aea9..07195a15 100644
--- a/docs/chapters/releases.sgml
+++ b/docs/chapters/releases.sgml
@@ -8,11 +8,11 @@
     release or anytime between releases.</para> 
     <para>
     The simplest way is doing all the changes to the
-    <emphasis>debian</emphasis>-branch without touching
+    <option>debian-branch</option> without touching
     <emphasis>debian/changelog</emphasis> at all. Then, when done, do:
     </para>
 <screen>
-&git-dch; --release
+&git-dch; <option>--release</option>
 </screen>
     <para> This will look up the latest released version in the changelog,
     increment the version in the &debian; changelog, generate changelog
@@ -22,7 +22,7 @@
     <para>
     But what if you want to have an (unreleased) snapshot for intermediate testing:
 <screen>
-&git-dch; --snapshot
+&git-dch; <option>--snapshot</option>
 </screen>
    <para>will generate a snapshot release with a specially crafted version number
    and a warning in the changelog that this is a snapshort release:
@@ -39,19 +39,19 @@ git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low
    commit id of the current branch head, &git-dch; can figure out what to
    append to the changelog by itself:
 <screen>
-&git-dch; --snapshot --auto
+&git-dch; <option>--snapshot</option> <option>--auto</option>
 </screen>
    will fetch the commit id and add changelog entries from that point to the
    current HEAD - again auto incrementing the version number. If you don't want
    to start at that commit id, you can specify any id or tag with:</para>
 <screen>
-&git-dch; --since=e76a6a180a57701ae4ae381f74523cacb3152780 --snapshot
+&git-dch; <option>--since</option>=<replaceable>e76a6a180a57701ae4ae381f74523cacb3152780</replaceable> <option>--snapshot</option>
 </screen>
    <para>
    After testing you can remove the snapshot header by a final &git-dch; call:
    </para>
 <screen>
-&git-dch; --since=HEAD --release
+&git-dch; <option>--since</option>=<replaceable>HEAD</replaceable> <option>--release</option>
 </screen>
    <para>
    This will add no further entries but simply remove the specially crafted
@@ -60,18 +60,18 @@ git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low
    entries - or you can (of course) use <option>--auto</option> again.
    </para>
 <sect1 id="gbp.release.numbers">
-    <title>Special snapshot numbers</title>
+    <title>Customizing snapshot numbers</title>
     <para>If the auto incrementing of the snapshot number doesn't suite you needs you
     can give any python expression that evaluates to a positive integer to
     calculate the new snapshot number:</para>
 <screen>
-&git-dch; -S -a --snapshot-number=1
-&git-dch; -S -a --snapshot-number='snapshot + 2'
-&git-dch; -S -a --snapshot-number='os.popen("git-log --pretty=oneline | wc -l").readlines()[0]'
-&git-dch; -S -a --snapshot-number=`git-log --pretty=oneline debian/0.3.3 | wc -l`
+&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>1</replaceable>
+&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>'snapshot + 2'</replaceable>
+&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>'os.popen("git-log --pretty=oneline | wc -l").readlines()[0]'</replaceable>
+&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>`git-log --pretty=oneline debian/0.3.3 | wc -l`</replaceable>
 </screen>
 <para>
-You can also add the snapshot-number calculation to gbp.conf:
+You can also add the snapshot-number calculation to <filename>gbp.conf</filename>:
 </para>
 <programlisting>
 [DEFAULT]
diff --git a/docs/chapters/special.sgml b/docs/chapters/special.sgml
index fcf46c2d..3ab3bc3d 100644
--- a/docs/chapters/special.sgml
+++ b/docs/chapters/special.sgml
@@ -8,55 +8,59 @@
 &gitcmd; branch dfsg_clean upstream
     </screen>
     <para>
-    This creates the <emphasis>dfsg_clean</emphasis> branch from the tip of
-    your <emphasis>upstream</emphasis> branch.  Then, when importing a new
+    This creates the <emphasis>dfsg_clean</emphasis> branch from the tip of a
+    branch called <emphasis>upstream</emphasis>.  Then, when importing a new
     upstream version, you import the new version on the
-    <emphasis>upstream</emphasis> branch as usual and just don't merge to the
-    master branch by default:
+    <option>upstream-branch</option> (by default named
+    <emphasis>upstream</emphasis>) as usual and just don't merge to the
+    <emphasis>debian-branch</emphasis>  (by default named
+    <emphasis>master</emphasis>):
     </para>
     <screen>
-&git-import-orig; --no-merge nondfsg-clean-package_10.4.orig.tar.gz
-&gitcmd; tag 10.4
+&git-import-orig; --no-merge <filename>/path/to/nondfsg-clean-package_10.4.orig.tar.gz</filename>
+&gitcmd; <option>tag</option> 10.4
     </screen>
     <para>
-    After the import you can switch to the dfsg branch and get the newly
-    imported changes from the upstream branch:
+    After the import you can switch to the <emphasis>dfsg_clean</emphasis>
+    branch and get the newly imported changes from the upstream branch:
     </para>
     <screen>
-&gitcmd; checkout dfsg_clean
-&gitcmd; pull . upstream
+&gitcmd; <option>checkout</option> dfsg_clean
+&gitcmd; <option>pull</option> <filename>.</filename> upstream
     </screen>
-    <para>
-    Now make this dfsg clean (preverably by a cleanup script), commit your changes and merge to the master branch:
-    </para>
+    <para>Now make this checkout dfsg clean (preverably by a cleanup script), commit
+    your changes and merge to your <option>debian-branch</option>:</para>
     <screen>
 cleanup-script.sh
 &gitcmd; commit -a -m "Make source dfsg clean"
-&gitcmd; tag 10.4.dfsg
-&gitcmd; checkout master
-&gitcmd; pull . dfsg_clean
+&gitcmd; tag <replaceable>10.4.dfsg</replaceable>
+&gitcmd; checkout <replaceable>master</replaceable>
+&gitcmd; pull <replaceable>.</replaceable> <replaceable>dfsg_clean</replaceable>
     </screen>
 
     <sect1 id="gbp.special.nmus">
     <title>Importing NMUs</title>
     <para>
-    First create a branch that holds the NMUs once:
+    First create a branch that holds the NMUs from the tip of your
+    <option>debian-branch</option> (default is <emphasis>master</emphasis>) once:
     </para>
     <screen>
-&gitcmd; <option>branch</option> <replaceable>nmu</replaceable>
+&gitcmd; <option>branch</option> <replaceable>nmu</replaceable> <replaceable>master</replaceable>
     </screen>
     <para>
     To import an NMU instead of a new upstream version simply import the
-    unpacked NUMs source tree into your repository:
+    unpacked NUMs source tree into your repository using &git-import-orig:
     </para>
     <screen>
-&gitcmd; checkout master
-&git-import-orig; -u 10-1.1 --upstream-branch=nmu /path/to/nmu-10/
+&gitcmd; checkout <replaceable>master</replaceable>
+&git-import-orig; <option>-u</option> <replaceable>10-1.1</replaceable> <option>--upstream-branch</option>=<replaceable>nmu</replaceable> <filename>/path/to/nmu-10/</filename>
     </screen>
     <para>
-    This will import the NMU on the <emphasis>nmu</emphasis> branch instead of
-    the <emphasis>upstream</emphasis> branch but merge the changes to the
-    <emphasis>master</emphasis> branch as usual.
+    This will import the NMU onto the branched named <emphasis>nmu</emphasis> branch instead of
+    the default <option>upstream-branch</option> and merge the changes to the
+    <option>debian-branch</option> as usual. This method can also be used to
+    import "old" releases into the &git; repository when migrating to &git; from
+    another VCS.
     </para>
     </sect1>
 
@@ -64,15 +68,15 @@ cleanup-script.sh
     <title>Using &pbuilder;</title>
     <para>
     Since pbuilder use different command line arguments than
-    &debuild; and &dpkg-buildpackage; we have to use a small script that's
+    &debuild; and &dpkg-buildpackage; we have to use a tiny script that gets
     invoked by &git-buildpackage;:
 <programlisting>
 cat &lt;&lt;EOF &gt;/usr/local/bin/git-pbuilder
 #!/bin/sh
 # pass all options to dpkg-buildpackage:
-pdebuild --debbuildopts "-i\.git -I.git $*"
+<command>pdebuild</command> <option>--debbuildopts</option> "-i\.git -I.git $*"
 EOF
-chmod a+x /usr/local/bin/git-pbuilder
+<command>chmod</command> a+x /usr/local/bin/git-pbuilder
 </programlisting>
 
     Furthermore we need a different clean command, since &pdebuildcmd;
@@ -100,7 +104,7 @@ builder = /usr/local/bin/git-pbuilder
     <title>Working on random packages</title>
     <para>
     Whenever you need to work on an arbitrary Debian package you can check it
-    right into &git;:
+    right into &git; with one command:
 <programlisting>
 apt-get source --download-only <filename>package</filename>
 git-import-dsc <filename>package</filename>*.dsc
@@ -108,11 +112,11 @@ cd <filename>package</filename>
 git-branch debian
 </programlisting>
     <para>
-    This puts the orig.tar.gz onto the <emphasis>upstream</emphasis> branch and
-    the Debian patch onto branch <emphasis>debian</emphasis>. Now you can
-    easily modify the package on the master branch, revert changes you made,
-    create other branches for testing, see what changes you made, etc.. When
-    finished just do</para>
+    This puts the orig.tar.gz onto the <option>upstream-branch</option> and
+    the Debian patch onto a branch called <emphasis>debian</emphasis>. Now you
+    can easily modify the package, revert changes you made, create other
+    branches for testing, see what changes you made, etc..  When finished just
+    do</para>
 <programlisting>
 git-commit -a
 git-diff debian --
diff --git a/docs/common.ent b/docs/common.ent
index c2f26502..58e97303 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -20,6 +20,7 @@
   <!ENTITY pbuilder    "<productname>Pbuilder</productname>">
   <!ENTITY gitloaddirs "<productname>Git_load_dirs</productname>">
   <!ENTITY debuild     "<productname>Debuild</productname>">
+  <!ENTITY svn-buildpackage "<productname>svn-buildpackage</productname>">
   <!ENTITY gpg 	       "<productname>GPG</productname>">
   <!ENTITY dpkg-buildpackage "<productname>Dpkg-buildpackage</productname>">
   <!ENTITY gnu         "<acronym>GNU</acronym>">
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 7a00f0b1..ad563597 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -4,7 +4,7 @@
 <!ENTITY man.git.dch SYSTEM "git-dch.sgml">
 <!ENTITY man.git.config-files "
     <title>CONFIGURATION FILES</title>
-    <para> Three configuration files are parsed to set defaults for the above
+    <para>Four configuration files are parsed to set defaults for the above
     commandline arguments: </para>
     <variablelist>
       <varlistentry>
@@ -16,10 +16,15 @@
       <listitem><para>per user configuration</para></listitem>
       </varlistentry>
       <varlistentry>
+      <term>.gbp.conf</term>
+      <listitem><para>per branch configuration, can be published with the
+      repository</para></listitem> 
+      </varlistentry> 
+      <varlistentry>
       <term>.git/gbp.conf</term>
-      <listitem><para>per working copy configuration</para></listitem> 
+      <listitem><para>per repository configuration</para></listitem> 
       </varlistentry> 
     </variablelist>
       <para>
-      See /etc/git-buildpackage/gbp.conf for an example.
+      See <filename>/etc/git-buildpackage/gbp.conf</filename> for an example.
       </para>">