Merge 0.4.5 into bpo-etch

Conflicts:

	debian/changelog

33 files changed, 1235 insertions, 238 deletions

diff --git a/TODO b/TODO
index 9fda9299..517aeb25 100644
--- a/TODO
+++ b/TODO
@@ -1,8 +1,9 @@
 - git-buildpackage:
-  - allow to export the hole source tree to tmpdir before building
   - allow to fetch and build from a signed tag even when it's in a remote repo
 - git-import-orig:
-  - allow to import into an empty repository
   - show untracked files using 'git-ls-files -o' after import
 - git-import-dsc:
   - allow to import into a git repository for backports
+- git-dch
+  - make format of log messages more flexible
+  - don't forcibly start a new version
diff --git a/debian/NEWS b/debian/NEWS
index 7eeace09..e98be909 100644
--- a/debian/NEWS
+++ b/debian/NEWS
@@ -1,3 +1,18 @@
+git-buildpackage (0.3.3) unstable; urgency=low
+
+  As of this version git-buildpackage doesn't pass hardcoded '-i\.git -I.git'
+  to the build command specified via --git-builder (or via the builder config
+  file options). So if you're not using the default build command (which is
+  now 'debuild -i\.git -I.git' instead of just plain 'debuild') you'll have to
+  add these options to your build command in order to exclude git metadata
+  from your diffs and source tarballs.
+  This was done to make the invocation of the build command more flexible, we
+  don't rely on debuild behaviour from now on.
+  Again: if you didn't change the default build command, you don't have to
+  change anything.
+
+ -- Guido Guenther <agx@sigxcpu.org>  Mon, 20 Aug 2007 18:08:37 +0200
+
 git-buildpackage (0.2.25) unstable; urgency=low
 
   Generated tags are now by default put into debian/ and upstream/ namespaces.
diff --git a/debian/changelog b/debian/changelog
index fa6859e4..33b017f9 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,108 @@
+git-buildpackage (0.4.5) unstable; urgency=low
+
+  * git-import-orig: fix missing s/upstream/upstream_branch/ rename
+    (Closes: #447920) - Thanks to Arnaud Cornet
+
+ -- Guido Guenther <agx@sigxcpu.org>  Wed, 24 Oct 2007 22:56:24 +0200
+
+git-buildpackage (0.4.4) unstable; urgency=low
+
+  * git-buildpackage: use upstream-branch in case the tag doesn't exist
+
+ -- Guido Guenther <agx@sigxcpu.org>  Mon, 22 Oct 2007 17:00:12 +0200
+
+git-buildpackage (0.4.3) experimental; urgency=low
+
+  * git-dch: properly quote "" (Closes: #447211)
+  * git-dch: use Command() instead of implementing it again
+  * documentation updates
+  * don't split up the manual that much (local.dsl taken from
+    darcs-buildpackage)
+  * add version number to docs and a tools (--version)
+  * pylint and other consistency updates
+
+ -- Guido Guenther <agx@sigxcpu.org>  Fri, 19 Oct 2007 10:12:40 +0200
+
+git-buildpackage (0.4.2) experimental; urgency=low
+
+  * git-dch:
+       * make --git-log a config file option
+       * git-dch: fix help message for --debian-branch
+       * doc: snapshot-number can be used in gbp.conf too
+  * git-buildpackage:
+       * add --git-export-dir=dir/, --git-export=treeish (Closes: #446042)
+       * allow to use any treeish object for --git-upstream-branch
+  * add missing examples to gbp.conf
+  * parse .gbp.conf in the repository directory (Closes: #426009)
+  * minor doc updates and clarifications
+
+ -- Guido Guenther <agx@sigxcpu.org>  Wed, 17 Oct 2007 00:00:13 +0200
+
+git-buildpackage (0.4.1) unstable; urgency=low
+
+  * make sure the changelog section's trailer points to the person
+    invoking git-dch
+  * depend on devscripts with a working 'dch ""'
+  * git-dch: eval() the snapshot number calculation
+
+ -- Guido Guenther <agx@sigxcpu.org>  Wed, 10 Oct 2007 18:15:54 +0200
+
+git-buildpackage (0.4.0) experimental; urgency=low
+
+  * add support for automatic snapshot releases as suggested by Ottavio
+    Salvador
+  * make git-dch actually useful:
+      * --auto: guess last changelogged commit from the snapshot header
+      * add short options for --snapshot and --release
+      * don't fail if the commit msg starts with '--'
+      * add a check for the debian branch instead of always using it as the
+        tip
+      * handle versions containing epochs
+      * add --git-log to pass options along to git-log
+      * allow to specify paths to look at: git-dch path1 path2 - useful if
+        upstream uses git
+  * add some basic documentation for git-dch
+
+ -- Guido Guenther <agx@sigxcpu.org>  Sun, 07 Oct 2007 15:32:40 +0200
+
+git-buildpackage (0.3.6) unstable; urgency=low
+
+  * create upstream branch when importing into an empty archive 
+    (Closes: #443305)
+  * detect upstream version from common tarball formats 
+    (Closes: #443306)
+
+ -- Guido Guenther <agx@sigxcpu.org>  Wed, 03 Oct 2007 18:01:15 +0200
+
+git-buildpackage (0.3.5) unstable; urgency=low
+
+  * add a minimalistic git-dch that creates changelog entries from git commit
+    messages
+  * s/reopsitory/repository/ - thanks to Loïc Minier (Closes: #444702)
+  * update TODO
+  * short paragraph on hacking on arbitrary debian packages
+
+ -- Guido Guenther <agx@sigxcpu.org>  Wed, 03 Oct 2007 14:10:05 +0200
+
+git-buildpackage (0.3.4) unstable; urgency=low
+
+  * introduce --git-no-create-orig to skip building of any orig.tar.gz - this
+    is especially usefull if you're working on an NMU that has a X-0.Y version
+    number although it's a Debian native package
+  * fix the error path in case the tgz can't be unpacked
+  * git-pbuilder: add filter for git meta data and allow to pass options to
+    pbuilder vi $PBUILDER_OPTS (Closes: #439535)
+
+ -- Guido Guenther <agx@sigxcpu.org>  Sat, 08 Sep 2007 20:40:36 +0200
+
+git-buildpackage (0.3.3) unstable; urgency=low
+
+  * git-buildpackage: don't hardcode -i\.git -I.git as build arguments
+    (Closes: #438669)
+  * git-import-dsc: support --debian-branch (Closes: #432084)
+
+ -- Guido Guenther <agx@sigxcpu.org>  Mon, 20 Aug 2007 19:22:24 +0200
+
 git-buildpackage (0.3.2~bpo.1) etch-backports; urgency=low
 
   * etch backport 
diff --git a/debian/control b/debian/control
index 607ec3d3..2bbff711 100644
--- a/debian/control
+++ b/debian/control
@@ -9,7 +9,7 @@ XS-Vcs-Git: http://honk.sigxcpu.org/git/git-buildpackage.git/
 
 Package: git-buildpackage
 Architecture: all
-Depends: ${python:Depends}, ${shlibs:Depends}, ${misc:Depends}, devscripts,
+Depends: ${python:Depends}, ${shlibs:Depends}, ${misc:Depends}, devscripts (>= 2.10.9),
  git-core (>= 1:1.5.0.1-1)
 Suggests: git-load-dirs
 Description: Suite to help with Debian packages in Git repositories
@@ -19,3 +19,4 @@ Description: Suite to help with Debian packages in Git repositories
   * git-import-orig: import a new upstream version into the git repository
   * git-buildpackage: build a package out of a git repository, check for local
     modifications and tag appropriately
+  * git-dch: generate Debian changelog entries from Git commit messages
diff --git a/debian/rules b/debian/rules
index eff6c1fa..3474e37d 100755
--- a/debian/rules
+++ b/debian/rules
@@ -7,26 +7,36 @@ DEB_PYTHON_CLEAN_ARGS = --all
 include /usr/share/cdbs/1/rules/debhelper.mk
 include /usr/share/cdbs/1/class/python-distutils.mk
 
-COMMANDS=git-buildpackage git-import-dsc git-import-orig
+COMMANDS=git-buildpackage git-import-dsc git-import-orig git-dch
 MANPAGES=$(patsubst %,docs/%.1,$(COMMANDS))
 MANUAL=docs/manual-html
 PYCHECKS=$(patsubst %,%.py,$(COMMANDS))
 PYCHECK_LEVEL=Error
+GBP_VERSION=gbp/gbp_version.py
+VERSION_ENT=docs/version.ent
 
 docs/%.1: docs/man.%.sgml
 	docbook2man -o docs/ $<
 
+docs/manual.sgml: docs/version.ent
+
 $(MANUAL): docs/manual.sgml docs/chapters/*.sgml docs/manpages/*.sgml
-	docbook-2-html -s gtk $<
+	docbook-2-html -s local $<
 
 %.py: %
 	ln -s $< $@
 	PYTHONPATH=. pychecker -e $(PYCHECK_LEVEL) -q $<
 
-build/git-buildpackage:: $(MANPAGES) $(MANUAL) $(PYCHECKS)
+$(GBP_VERSION): debian/changelog
+	echo 'gbp_version="$(DEB_VERSION)"' > $(GBP_VERSION)
+
+$(VERSION_ENT): debian/changelog
+	echo '<!ENTITY gbp-version "$(DEB_VERSION)">' >  $(VERSION_ENT)
+
+build/git-buildpackage:: $(MANPAGES) $(MANUAL) $(GBP_VERSION) $(PYCHECKS) 
 
 clean::
 	-rm git-*.py
-	-rm docs/*.1 docs/manpage.*
+	-rm docs/*.1 docs/manpage.* $(VERSION_ENT)
 	-rm -r docs/manual-html/
 
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 26dc5230..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,18 +53,16 @@
 <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
+builder=debuild -i\.git -I.git
 # the default branch for upstream sources
 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/chapters.ent b/docs/chapters/chapters.ent
index 68fea426..fd7c6da3 100644
--- a/docs/chapters/chapters.ent
+++ b/docs/chapters/chapters.ent
@@ -2,5 +2,6 @@
 <!ENTITY ch.workflow SYSTEM "workflow.sgml">
 <!ENTITY ch.import SYSTEM "import.sgml">
 <!ENTITY ch.building SYSTEM "building.sgml">
+<!ENTITY ch.releases SYSTEM "releases.sgml">
 <!ENTITY ch.cfgfile SYSTEM "cfgfile.sgml">
 <!ENTITY ch.special SYSTEM "special.sgml">
diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
index 18c331cb..1bbca3f0 100644
--- a/docs/chapters/import.sgml
+++ b/docs/chapters/import.sgml
@@ -3,42 +3,44 @@
 
     <sect1 id="gbp.import.existing">
     <title>Importing already existing &debian; packages</title>
-    <para>Imporing an already exsting debian package into a git repository is as easy as:
+    <para>Importing an already exsting debian package into a git repository is as easy as:
     <screen>
 &git-import-dsc; package_0.1-1.dsc
     </screen>
-    This will 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
-    <option>--upstream-branch</option> and <option>--debian-branch</option> options.
+    This will create a new git repository named after the imported package, put
+    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 or via the <option>upstream-branch</option> and
+    <option>debian-branch</option> options in the configuration file.
     </para>
     </sect1>
 
     <sect1 id="gbp.import.new.upstream">
     <title>Importing a new upstream version</title>
-    <para>Change into your git repository, make sure it has all local
-    modifications committed and run either of:
+    <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>
@@ -53,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>
@@ -87,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>
@@ -105,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 4097793d..32e9b83b 100644
--- a/docs/chapters/intro.sgml
+++ b/docs/chapters/intro.sgml
@@ -5,45 +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 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
new file mode 100644
index 00000000..07195a15
--- /dev/null
+++ b/docs/chapters/releases.sgml
@@ -0,0 +1,81 @@
+<chapter id="gbp.releases">
+    <title>Releases and Snapshots</title>
+    <para>When branching and merging frequently, the different Debian changelog
+    entries on the different branches tend to get into the way of the automatic
+    merge and the the merge fails - leaving the (patholigical) merge to the
+    committer. In order to avoid this &git-dch; offers a way for creating
+    changelog entries from &git; commits before doing a
+    release or anytime between releases.</para> 
+    <para>
+    The simplest way is doing all the changes to the
+    <option>debian-branch</option> without touching
+    <emphasis>debian/changelog</emphasis> at all. Then, when done, do:
+    </para>
+<screen>
+&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
+    messages from the corresponding &git; commit id up to the branch head and
+    finally spawns an editor for final changelog file editing by invoking &dch;
+    <option>--release</option>.</para>
+    <para>
+    But what if you want to have an (unreleased) snapshot for intermediate testing:
+<screen>
+&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:
+   </para>
+<programlisting>
+git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low
+
+  ** SNAPSHOT build @470ce29ec7877705c844474a2fd89869aea0406d **
+
+  * add support for automatic snapshot 
+</programlisting>
+   <para>During subsequent calls with <option>--snapshot</option> this version
+   number will continue to increase. Since the snapshot banners contains the
+   commit id of the current branch head, &git-dch; can figure out what to
+   append to the changelog by itself:
+<screen>
+&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; <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; <option>--since</option>=<replaceable>HEAD</replaceable> <option>--release</option>
+</screen>
+   <para>
+   This will add no further entries but simply remove the specially crafted
+   version number and the snapshort header. Again you can use any commit id
+   or tag instead of <option>HEAD</option> if you want to add further changelog
+   entries - or you can (of course) use <option>--auto</option> again.
+   </para>
+<sect1 id="gbp.release.numbers">
+    <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; <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 <filename>gbp.conf</filename>:
+</para>
+<programlisting>
+[DEFAULT]
+snapshot-number = os.popen("git-log --pretty=oneline | wc -l").readlines()[0]
+</programlisting>
+</sect1>
+</chapter>
diff --git a/docs/chapters/special.sgml b/docs/chapters/special.sgml
index 9fa78747..3ab3bc3d 100644
--- a/docs/chapters/special.sgml
+++ b/docs/chapters/special.sgml
@@ -1,4 +1,4 @@
-<chapter id="gbp.special">
+    <chapter id="gbp.special">
     <title>Special usage cases</title>
     <sect1 id="gbp.special.dfsgfree">
     <title>Handling non-DFSG clean upstream sources</title>
@@ -8,76 +8,75 @@
 &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
-    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:
+    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
+    <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 you can use:
+    To import an NMU instead of a new upstream version simply import the
+    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 nmu-10-1.1.tar.gz
+&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>
-    <note>
-    <para>
-    You need to have the NMU as a single tar.gz, you can't use the
-    dsc and diff.gz here, this will be fixed in a later version.
-    <para>
-    </note>
     </sect1>
 
     <sect1 id="gbp.special.pbuilder">
     <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 "$*"
+<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;
@@ -101,4 +100,29 @@ builder = /usr/local/bin/git-pbuilder
      put this into <filename>.git/gbp.conf</filename> in one of your &git; repositories.
     </para>
 
+    <sect1 id="gbp.special.hacking">
+    <title>Working on random packages</title>
+    <para>
+    Whenever you need to work on an arbitrary Debian package you can check it
+    right into &git; with one command:
+<programlisting>
+apt-get source --download-only <filename>package</filename>
+git-import-dsc <filename>package</filename>*.dsc
+cd <filename>package</filename>
+git-branch debian
+</programlisting>
+    <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 --
+</programlisting>
+    <para>
+    to get a nice patch that can be submitted to the Debian BTS.
+    </para>
+    </sect1>
 </chapter>
diff --git a/docs/common.ent b/docs/common.ent
index 7c4d38da..28cd7d39 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -1,12 +1,12 @@
   <!ENTITY dhfirstname 		"<firstname>Guido</firstname>">
   <!ENTITY dhsurname   		"<surname>Guenther</surname>">
-  <!ENTITY dhdate      		"<date>2006-10-02</date>">
   <!ENTITY dhsection   		"<manvolnum>1</manvolnum>">
   <!ENTITY dhemail     		"<email>agx@sigxcpu.org</email>">
   <!ENTITY dhusername  		"Guido Guenther">
   <!ENTITY git-buildpackage 	"<command>git-buildpackage</command>">
   <!ENTITY git-import-orig	"<command>git-import-orig</command>">
   <!ENTITY git-import-dsc	"<command>git-import-dsc</command>">
+  <!ENTITY git-dch		"<command>git-dch</command>">
   <!ENTITY gitcmd		"<command>git</command>">
   <!ENTITY gitkcmd		"<command>gitk</command>">
   <!ENTITY pbuildercmd		"<command>pbuilder</command>">
@@ -15,9 +15,11 @@
 
   <!ENTITY debian      "<productname>Debian</productname>">
   <!ENTITY git	       "<productname>Git</productname>">
+  <!ENTITY dch	       "<productname>dch</productname>">
   <!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/copyright.sgml b/docs/copyright.sgml
index f9ea8515..66609da8 100644
--- a/docs/copyright.sgml
+++ b/docs/copyright.sgml
@@ -1,6 +1,6 @@
   <para>
     git-buildpackage, all associated scripts and programs, this manual,
-    and all build scripts are Copyright &copy; 2006 Guido Guenther.
+    and all build scripts are Copyright &copy; 2006,2007 Guido Guenther.
   </para>
       <para>
         This program is free software; you can redistribute it and/or modify
diff --git a/docs/local.dsl b/docs/local.dsl
new file mode 100644
index 00000000..a9a6d052
--- /dev/null
+++ b/docs/local.dsl
@@ -0,0 +1,34 @@
+<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY dbstyle PUBLIC "-//GtkViaAlcove//DOCUMENT Gtk-doc HTML Stylesheet//EN" CDATA DSSSL>
+]>
+
+<style-sheet>
+<style-specification use="gtk">
+<style-specification-body>
+
+;; Don't split up the doc as much.
+(define (chunk-element-list)
+  (list (normalize "preface")
+        (normalize "chapter")
+        (normalize "appendix")
+        (normalize "article")
+        (normalize "glossary")
+        (normalize "bibliography")
+        (normalize "index")
+        (normalize "colophon")
+        (normalize "setindex")
+        (normalize "reference")
+        (normalize "refentry")
+        (normalize "part")
+        (normalize "book") ;; just in case nothing else matches...
+        (normalize "set")  ;; sets are definitely chunks...
+        ))
+
+</style-specification-body>
+</style-specification>
+<external-specification id="gtk" document="dbstyle">
+</style-sheet>
+
+<!--
+# arch-tag: web stylesheet for documentation
+-->
diff --git a/docs/man.git-dch.sgml b/docs/man.git-dch.sgml
new file mode 100644
index 00000000..797f372a
--- /dev/null
+++ b/docs/man.git-dch.sgml
@@ -0,0 +1,11 @@
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+  <!ENTITY % COMMON SYSTEM "common.ent">
+  %COMMON;
+  <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+  %MANPAGES;
+]>
+
+<reference>
+<title>git-buildpackage Manual</title>
+&man.git.dch;
+</reference>
diff --git a/docs/manpages/git-buildpackage.sgml b/docs/manpages/git-buildpackage.sgml
index ae8eadf4..473ca1e0 100644
--- a/docs/manpages/git-buildpackage.sgml
+++ b/docs/manpages/git-buildpackage.sgml
@@ -22,7 +22,7 @@
       <arg><option>--git-ignore-new</option></arg>
       <arg><option>--git-tag</option></arg>
       <arg><option>--git-verbose</option></arg>
-      <arg><option>--git-upstream-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg><option>--git-upstream-branch=</option><replaceable>treeish</replaceable></arg>
       <arg><option>--git-debian-branch=</option><replaceable>branch_name</replaceable></arg>
       <arg><option>--git-builder=</option><replaceable>BUILD_CMD</replaceable></arg>
       <arg><option>--git-cleaner=</option><replaceable>CLEAN_CMD</replaceable></arg>
@@ -30,6 +30,9 @@
       <arg><option>--git-keyid=</option><replaceable>gpg-keyid</replaceable></arg>
       <arg><option>--git-posttag=</option><replaceable>command</replaceable></arg>
       <arg><option>--git-debian-tag=</option><replaceable>tag-format</replaceable></arg>
+      <arg><option>--git-no-create-orig</option></arg>
+      <arg><option>--git-export-dir=</option><replaceable>directory</replaceable></arg>
+      <arg><option>--git-export=</option><replaceable>treeish</replaceable></arg>
     </cmdsynopsis>
   </refsynopsisdiv>
   <refsect1>
@@ -44,12 +47,15 @@
         <listitem><para>Verify that it is being executed from the
             proper location.</para>
         </listitem>
-	<listitem><para>Verify that the reopository doesn't contain any
+	<listitem><para>Verify that the repository doesn't contain any
 	uncommitted source changes.</para>
 	</listitem>
         <listitem><para>Verify that it is being executed from the
         correct branch.</para>
         </listitem>
+	<listitem><para>
+	(Optionally) export the source tree to a separate build area
+	</para></listitem>
         <listitem><para>Build an orig.tar.gz if it doesn't exist.</para>
         </listitem>
         <listitem><para>Call <application>debuild</application>(1)
@@ -59,6 +65,13 @@
             &git-buildpackage; that don't start with --git-.
           </para>
         </listitem>
+	<listitem><para>
+	(Optionally) tag the tree after a successful build
+	</para></listitem>
+	<listitem><para>
+	(Optionally) call a post-tag hook - e.g. to push the results to a remote
+	repository after creating the tag
+	</para></listitem>
     </itemizedlist>
   </refsect1>
   <refsect1>
@@ -83,7 +96,7 @@
       <varlistentry>
         <term><option>--git-builder=<replaceable>BUILD_CMD</replaceable></option></term>
         <listitem>
-          <para>Use <replaceable>BUILD_CMD</replaceable> instead of <command>debuild</command></para>
+          <para>Use <replaceable>BUILD_CMD</replaceable> instead of <command>debuild -i\.git -I.git</command></para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -103,7 +116,10 @@
         <term><option>--git-upstream-branch</option>=<replaceable>branch_name</replaceable>
         </term>
         <listitem>
-	  <para>Branch to build the orig.tar.gz from. Default is <replaceable>upstream</replaceable></para>
+	  <para>Branch to build the orig.tar.gz from if no tag matching the
+	  upstream version is found. Default is
+	  <replaceable>upstream</replaceable>. You can give any treeish object
+	  here.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -146,6 +162,27 @@
           <para>use this tag format when tagging Debian versions</para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><option>--git-no-create-orig</option>
+        </term>
+        <listitem>
+	  <para>Don't try to create any orig.tar.gz</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--git-export-dir=</option><replaceable>directory</replaceable>
+        </term>
+        <listitem>
+          <para>Export the current branch head to <replaceable>directory</replaceable> before building.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--git-export=</option><replaceable>treeish</replaceable>
+        </term>
+	<listitem> <para>Instead of exporting the current branch head export at
+	the treeish object <replaceable>treeish</replaceable>.</para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
@@ -155,7 +192,7 @@
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para>git-import-dsc (1), git-import-orig (1), debuild (1), git (1)</para>
+    <para>git-import-dsc (1), git-import-orig (1), debuild (1), git (1), git-dch (1)</para>
 
   </refsect1>
   <refsect1>
diff --git a/docs/manpages/git-dch.sgml b/docs/manpages/git-dch.sgml
new file mode 100644
index 00000000..0208a651
--- /dev/null
+++ b/docs/manpages/git-dch.sgml
@@ -0,0 +1,147 @@
+<refentry id="gbp.man.git.dch">
+  <refentryinfo>
+    <address>
+      &dhemail;
+    </address>
+    <author>
+      &dhfirstname;
+      &dhsurname;
+    </author>
+  </refentryinfo>
+  <refmeta>
+   <refentrytitle>git-dch</refentrytitle> 
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>&git-dch;</refname>
+
+    <refpurpose>Generate the Debian changelog from git commit messages</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      &git-dch;
+
+      <arg><option>--verbose</option></arg>
+      <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg><option>--debian-tag=</option><replaceable>tag-format</replaceable></arg>
+      <arg><option>--since=</option><replaceable>commitish</replaceable></arg>
+      <arg><option>--snapshot</option></arg>
+      <arg><option>--release</option></arg>
+      <arg><option>--auto</option></arg>
+      <arg><option>--snapshot-number=</option><replaceable>expression</replaceable></arg>
+      <arg><option>--git-log=</option><replaceable>git-log-options</replaceable></arg>
+      <arg choice="plain"><replaceable>[path1 path2]</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+    &git-dch; reads git commit messages and generates the debian changelog from
+    it. If no arguments are given &git-dch; starts from the last tagged debian
+    package version up to the current tip of the current branch. If the
+    distribution of the topmost section in
+    <filename>debian/changelog</filename> is <emphasis>UNRELEASED</emphasis>
+    the changelog entries will be inserted into this section. Otherwise a new
+    section will be created.</para>
+    <para>If <option>--auto</option> is given &git-dch; tries to guess the
+    last &git; commit documented in the changelog - this only works in snapshot
+    mode. Otherwise <option>--since</option> can be used to tell &git-dch;
+    at which point it should start in the &git; history.</para>
+    <para>
+    The additional path arguments can be used to restrict the repository paths
+    &git-dch; looks at. Setting <replaceable>path</replaceable> to
+    <emphasis>debian/</emphasis> is a good choice if upstream uses &git; and
+    all Debian packaging changes are restricted to the
+    <replaceable>debian/</replaceable> subdir. In more sophisticated cases
+    (like backports) you can use <option>--git-log</option> to restrict the
+    generated changelog entries further. E.g. by using 
+    <option>--git-log=</option><replaceable>"--author=Foo Bar"</replaceable>.</para>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>--debian-branch</option>=<replaceable>branch_name</replaceable>
+        </term>
+        <listitem>
+	  <para>The branch in the Git repository the Debian package is being
+	  developed on, default is <replaceable>master</replaceable>.
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--verbose</option></term> 
+	<term><option>-v</option></term>
+        <listitem>
+          <para>verbose execution</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--debian-tag=</option><replaceable>tag-format</replaceable>
+        </term>
+        <listitem>
+          <para>tag format used, when tagging debian versions</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--since=</option><replaceable>committish</replaceable>
+        </term>
+        <listitem>
+          <para>start reading commit messages at <replaceable>committish</replaceable></para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--auto</option></term>
+        <listitem>
+	  <para>Guess the last commit documented in the changelog from the
+	  snapshot banner (or from the last tag if no snapshot banner exists).
+	  </para>
+        </listitem>
+      <varlistentry>
+        <term><option>--snapshot</option></term>
+        <listitem>
+	  <para>create a snapshot release entry. This adds a snapshot release
+	  number and a warning banner to the changelog entry. The release
+	  version number is being autoincremented with every new snapshot
+	  release to avoid packages downgrades during snapshot testing.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--snapshot-number=</option><replaceable>expression</replaceable>
+        </term>
+        <listitem>
+          <para>Python expression that gets eval()ed to the new snapshot number</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--release</option></term>
+        <listitem>
+	  <para>Remove any snapshot release banners and version suffixes, set
+	  the current distribution to <replaceable>unstable</replaceable> and
+	  open the changelog for final tweaking.</para>
+        </listitem>
+      <varlistentry>
+        <term><option>--git-log=</option><replaceable>git-log-options</replaceable>
+        </term>
+        <listitem>
+          <para>options passed on verbatim to git-log(1)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+      &man.git.config-files;
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+
+    <para>git-buildpackage (1), git-import-dsc (1), git-import-orig (1), git (1), git_load_dirs (1)</para>
+
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+
+    <para>&dhusername; &dhemail;</para>
+
+  </refsect1>
+</refentry>
diff --git a/docs/manpages/git-import-dsc.sgml b/docs/manpages/git-import-dsc.sgml
index df783d32..38940f76 100644
--- a/docs/manpages/git-import-dsc.sgml
+++ b/docs/manpages/git-import-dsc.sgml
@@ -23,6 +23,7 @@
 
       <arg><option>--verbose</option></arg>
       <arg><option>--upstream-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
       <arg><option>--sign-tags</option></arg>
       <arg><option>--keyid=</option><replaceable>gpg-keyid</replaceable></arg>
       <arg><option>--debian-tag=</option><replaceable>tag-format</replaceable></arg>
@@ -53,6 +54,14 @@
         </listitem>
       </varlistentry>
       <varlistentry>
+        <term><option>--debian-branch</option>=<replaceable>branch_name</replaceable>
+        </term>
+        <listitem>
+	  <para>The branch in the &git; repository the debian sources are put
+	  onto. Default is <replaceable>master</replaceable>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
         <term><option>--verbose</option></term>
 	<term><option>-v</option></term>
         <listitem>
@@ -102,7 +111,7 @@
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para>git-buildpackage (1), git-import-orig (1), git (1), git_load_dirs (1)</para>
+    <para>git-buildpackage (1), git-import-orig (1), git (1), git_load_dirs (1), git-dch (1)</para>
   </refsect1>
   <refsect1>
     <title>AUTHOR</title>
diff --git a/docs/manpages/git-import-orig.sgml b/docs/manpages/git-import-orig.sgml
index 8553561c..a8900ddb 100644
--- a/docs/manpages/git-import-orig.sgml
+++ b/docs/manpages/git-import-orig.sgml
@@ -129,7 +129,7 @@
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para>git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1)</para>
+    <para>git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1), git-dch (1)</para>
 
   </refsect1>
   <refsect1>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 6f76421a..ad563597 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -1,9 +1,10 @@
 <!ENTITY man.git.importorig SYSTEM "git-import-orig.sgml">
 <!ENTITY man.git.importdsc SYSTEM "git-import-dsc.sgml">
 <!ENTITY man.git.buildpackage SYSTEM "git-buildpackage.sgml">
+<!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>
@@ -15,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>">
diff --git a/docs/manual.sgml b/docs/manual.sgml
index 0ffbe3fe..e72ebec5 100644
--- a/docs/manual.sgml
+++ b/docs/manual.sgml
@@ -1,6 +1,8 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   <!ENTITY % COMMON SYSTEM "common.ent">
   %COMMON;
+  <!ENTITY % VERSION SYSTEM "version.ent">
+  %VERSION;
   <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
   %MANPAGES;
   <!ENTITY % CHAPTERS SYSTEM "chapters/chapters.ent">
@@ -11,15 +13,15 @@
 <book id="gbp">
   <bookinfo>
     <title>Building Debian Packages with git-buildpackage</title>
-    <author>
-      &dhfirstname; &dhsurname; 
-    </author>
+    <author>&dhfirstname; &dhsurname;</author>
     <address>&dhemail;</address>
+    <subtitle>Version: &gbp-version;</subtitle>
   </bookinfo>
 
   &ch.intro;
   &ch.import;
   &ch.building;
+  &ch.releases;
   &ch.cfgfile;
   &ch.special;
 
@@ -28,6 +30,7 @@
     &man.git.buildpackage;
     &man.git.importdsc;
     &man.git.importorig;
+    &man.git.dch;
   </appendix>
   <appendix id="gbp.copyleft">
     <title>Copyright</title>
diff --git a/examples/git-pbuilder b/examples/git-pbuilder
index d8e62e3d..bb1798e9 100755
--- a/examples/git-pbuilder
+++ b/examples/git-pbuilder
@@ -1,8 +1,9 @@
-#!/bin/sh -e
-#
+#!/bin/sh
+# 
 # pbuilder helper for git-buildpackage
 # use this as "builder" in gbp.conf
+set -e
 
 # pass all options to dpkg-buildpackage:
-pdebuild --debbuildopts "$*"
+pdebuild $PBUILDER_OPTS --debbuildopts "-i\.git/ -I.git $*"
 
diff --git a/gbp.conf b/gbp.conf
index c4d0774b..57b4b444 100644
--- a/gbp.conf
+++ b/gbp.conf
@@ -2,7 +2,9 @@
 
 [DEFAULT]
 # the default build command:
-#builder = debuild
+#builder = debuild -i\.git/ -I.git
+# the default clean command:
+#cleaner = debuild clean
 # the default branch for upstream sources:
 #upstream-branch = upstream
 # the default branch for the debian patch:
@@ -11,7 +13,7 @@
 #upstream-tag = upstream/%(version)s
 #debian-tag = debian/%(version)s
 
-# Options only for git-buildpackage
+# Options only affecting git-buildpackage
 [git-buildpackage]
 #upstream-branch = dfsgclean
 # uncomment this to automatically GPG sign tags
@@ -20,13 +22,20 @@
 #keyid = 0xdeadbeef
 # push to a remote repository after a successful tag: 
 #posttag = git-push git.example.com
+# use this for more svn-buildpackage like bahaviour:
+#export-dir = ../build-area/
 
-# Options only for git-import-orig
+# Options only affecting git-import-orig
 [git-import-orig]
 #upstream-branch = newupstream
 #debian-branch = dfsgclean
 
-# Options only for git-import-dsc
+# Options only affecting git-import-dsc
 [git-import-dsc]
 #upstream-branch = svn-upstream
 
+# Options only affecting git-dch
+[git-dch]
+#git-log = --no-merges
+#snapshot-number = snapshot + 1
+
diff --git a/gbp/command_wrappers.py b/gbp/command_wrappers.py
index 8853f18d..f275474d 100644
--- a/gbp/command_wrappers.py
+++ b/gbp/command_wrappers.py
@@ -9,6 +9,7 @@ git-buildpackage and friends
 import subprocess
 import sys
 import os.path
+from errors import GbpError
 
 class CommandExecFailed(Exception):
     """Exception raised by the Command class"""
diff --git a/gbp/config.py b/gbp/config.py
index bc19dcd9..21d5f215 100644
--- a/gbp/config.py
+++ b/gbp/config.py
@@ -6,6 +6,7 @@
 from optparse import OptionParser
 from ConfigParser import SafeConfigParser
 import os.path
+from gbp.gbp_version import gbp_version
 
 class GbpOptionParser(OptionParser):
     """
@@ -22,35 +23,40 @@ class GbpOptionParser(OptionParser):
     @cvar config_files: list of config files we parse
     @type config_files: list
     """
-    defaults={ 'builder'         : 'debuild',
-               'cleaner'	     : 'debuild clean',
-               'debian-branch'   : 'master',
-               'upstream-branch' : 'upstream',
-               'sign-tags'	     : '',		# empty means False
-               'keyid'		     : '',
-               'posttag'         : '',
-               'debian-tag'      : 'debian/%(version)s',
-               'upstream-tag'    : 'upstream/%(version)s',
-               'filter'          : '',
+    defaults = { 'builder'         : 'debuild -i\.git/ -I.git',
+                 'cleaner'         : 'debuild clean',
+                 'debian-branch'   : 'master',
+                 'upstream-branch' : 'upstream',
+                 'sign-tags'       : '',      # empty means False
+                 'no-create-orig'  : '',      # empty means False
+                 'keyid'           : '',
+                 'posttag'         : '',
+                 'debian-tag'      : 'debian/%(version)s',
+                 'upstream-tag'    : 'upstream/%(version)s',
+                 'filter'          : '',
+                 'snapshot-number' : 'snapshot + 1',
+                 'git-log'         : '--no-merges',
+                 'export-dir'      : '',
              }
-    config_files=['/etc/git-buildpackage/gbp.conf',
-                  os.path.expanduser('~/.gbp.conf'),
-                  '.git/gbp.conf' ]
+    config_files = [ '/etc/git-buildpackage/gbp.conf',
+                     os.path.expanduser('~/.gbp.conf'),
+                     '.gbp.conf',
+                     '.git/gbp.conf' ]
 
     def __parse_config_files(self):
         """parse the possible config files and set appropriate values default values"""
-        parser=SafeConfigParser(self.defaults)
+        parser = SafeConfigParser(self.defaults)
         parser.read(self.config_files)
-        self.config=dict(parser.defaults())
+        self.config = dict(parser.defaults())
         if parser.has_section(self.command):
-            self.config=dict(parser.items(self.command, raw=True))
+            self.config.update(dict(parser.items(self.command, raw=True)))
 
     def __init__(self, command, prefix='', usage=None):
-        self.command=command
-        self.prefix=prefix
+        self.command = command
+        self.prefix = prefix
+        self.config = {}
         self.__parse_config_files()
-        OptionParser.__init__(self, usage=usage)
-
+        OptionParser.__init__(self, usage=usage, version='%s %s' % (self.command, gbp_version))
 
     def add_config_file_option(self, option_name, dest, help, **kwargs):
         """
@@ -63,7 +69,7 @@ class GbpOptionParser(OptionParser):
         @type help: string
         """
         OptionParser.add_option(self,"--%s%s" % (self.prefix, option_name), dest=dest,
-                                default=self.config[option_name], 
+                                default=self.config[option_name],
                                 help=help % self.config, **kwargs)
 
-# vim:et:ts=4:sw=4:
+# vim:et:ts=4:sw=4:et:sts=4:ai:set list listchars=tab\:»·,trail\:·:
diff --git a/gbp/deb_utils.py b/gbp/deb_utils.py
index f4bc854b..1ae8d105 100644
--- a/gbp/deb_utils.py
+++ b/gbp/deb_utils.py
@@ -20,7 +20,7 @@ def parse_changelog(changelog):
     if '-' in cp['Version']:
         upstream_version, cp['Debian-Version'] = cp['Version'].rsplit('-', 1)
         if ':' in upstream_version:
-            cp['Epoch'], cp['Upstream-Version'] = upstream_version.split(':',1)
+            cp['Epoch'], cp['Upstream-Version'] = upstream_version.split(':', 1)
         else:
             cp['Upstream-Version'] = upstream_version
     else:
diff --git a/gbp/git_utils.py b/gbp/git_utils.py
index f52550b3..9cfb0ec5 100644
--- a/gbp/git_utils.py
+++ b/gbp/git_utils.py
@@ -27,10 +27,10 @@ class GitRepository(object):
             raise GitRepositoryError
 
 
-    def __git_getoutput(self, command):
-        """Exec a git command and return the output"""
+    def __git_getoutput(self, command, args=[]):
+        """exec a git command and return the output"""
         output = []
-        popen = subprocess.Popen(['git', command], stdout=subprocess.PIPE)
+        popen = subprocess.Popen(['git', command] + args, stdout=subprocess.PIPE)
         while popen.poll() == None:
             output += popen.stdout.readlines()
         ret = popen.poll()
@@ -47,6 +47,13 @@ class GitRepository(object):
         return False
 
 
+    def has_treeish(self, treeish):
+        """check if the repository has the treeish object treeish"""
+        self.__check_path()
+        out, ret =  self.__git_getoutput('ls-tree', [ treeish ])
+        return [ True, False ][ret != 0]
+
+
     def get_branch(self):
         """on what branch is the current working copy"""
         self.__check_path()
diff --git a/git-buildpackage b/git-buildpackage
index 6817a820..147e98e5 100755
--- a/git-buildpackage
+++ b/git-buildpackage
@@ -20,20 +20,19 @@
 
 import sys
 import os, os.path
+import errno
 import pipes
+import time
 from gbp.git_utils import (GitRepositoryError, GitRepository, build_tag)
 from gbp.deb_utils import (parse_changelog, is_native, orig_file, has_orig)
-from gbp.command_wrappers import (GitTag, Command, CommandExecFailed)
+from gbp.command_wrappers import (GitTag, Command, CommandExecFailed, RemoveTree)
 from gbp.config import GbpOptionParser
 from gbp.errors import GbpError
 
 
-def create_orig(cp, output_dir, branch):
-    "create an orig.tar.gz in output_dir"
-    output = os.path.join(output_dir, orig_file(cp))
-    pipe = pipes.Template()
-    pipe.prepend('git-archive --format=tar --prefix=%s-%s/ %s' % (cp['Source'], cp['Upstream-Version'], branch), '.-')
-    pipe.append('gzip -c -9',  '--')
+def git_archive_pipe(prefix, pipe, output, treeish):
+    """run the git_archive pipe"""
+    pipe.prepend('git-archive --format=tar --prefix=%s/ %s' % (prefix, treeish), '.-')
     try:
         ret = pipe.copy('', output)
         if ret:
@@ -48,95 +47,188 @@ def create_orig(cp, output_dir, branch):
     return True
 
 
+def create_orig(cp, output_dir, treeish):
+    "create an orig.tar.gz in output_dir"
+    output = os.path.join(output_dir, orig_file(cp))
+    prefix = "%s-%s" % (cp['Source'], cp['Upstream-Version'])
+
+    pipe = pipes.Template()
+    pipe.append('gzip -c -9',  '--')
+    return git_archive_pipe(prefix, pipe, output, treeish)
+
+
+def dump_tree(export_dir, treeish):
+    "dump a tree to output_dir"
+    output_dir = os.path.dirname(export_dir)
+    prefix = os.path.basename(export_dir)
+    pipe = pipes.Template()
+    pipe.append('tar -C %s -xf -' % output_dir,  '-.')
+    return git_archive_pipe(prefix, pipe, '', treeish)
+
+
+def move_old_export(target):
+    """move a build tree away if it exists"""
+    try:
+        os.mkdir(target)
+    except OSError, (e, msg):
+        if e == errno.EEXIST:
+            os.rename(target, "%s.obsolete.%s" % (target, time.time()))
+
+
+def prepare_output_dir(dir):
+    output_dir = dir
+    if not dir:
+        output_dir = '..'
+    output_dir = os.path.abspath(output_dir)
+
+    try:
+        os.mkdir(output_dir)
+    except OSError, (e, msg):
+        if e != errno.EEXIST:
+            raise GbpError, "Cannot create output dir %s" % output_dir
+    return output_dir
+
+
 def main(argv):
-    output_dir = '..'
     changelog = 'debian/changelog'
+    default_tree = 'HEAD'
+    retval = 0
+    prefix = "git-"
 
-    args = [ arg for arg in argv[1:] if arg.find('--git-') == 0 ]
-    dpkg_args = [ arg for arg in argv[1:] if arg.find('--git-') == -1 ]
+    args = [ arg for arg in argv[1:] if arg.find('--%s' % prefix) == 0 ]
+    dpkg_args = [ arg for arg in argv[1:] if arg.find('--%s' % prefix) == -1 ]
 
-    if "--help" in dpkg_args:
-        args.append('--help')
+    for arg in [ "--help", "-h", "--version" ]:
+        if arg in dpkg_args:
+            args.append(arg)
 
-    parser = GbpOptionParser(command=os.path.basename(argv[0]), prefix='git-')
+    parser = GbpOptionParser(command=os.path.basename(argv[0]), prefix=prefix)
 
     parser.add_option("--git-ignore-new", action="store_true", dest="ignore_new", default=False,
                       help="build with uncommited changes in the source tree")
-    parser.add_option("--git-tag", action="store_true", dest="tag", default=False,
-                      help="tag after a successful build")
     parser.add_option("--git-verbose", action="store_true", dest="verbose", default=False,
                       help="verbose command execution")
-    parser.add_config_file_option(option_name="builder", dest="build_cmd",
+    parser.add_config_file_option(option_name="builder", dest="builder",
                       help="command to build the package, default is '%(builder)s'")
-    parser.add_config_file_option(option_name="cleaner", dest="clean_cmd",
+    parser.add_config_file_option(option_name="cleaner", dest="cleaner",
                       help="command to build the package, default is '%(cleaner)s'")
     parser.add_config_file_option(option_name="upstream-branch", dest="upstream_branch",
                       help="upstream branch, default is '%(upstream-branch)s'")
     parser.add_config_file_option(option_name="debian-branch", dest='debian_branch',
                       help="branch the debian patch is being developed on, default is '%(debian-branch)s'")
-    parser.add_config_file_option(option_name="sign-tags", dest="sign_tag",
+    parser.add_option("--git-tag", action="store_true", dest="tag", default=False,
+                      help="tag after a successful build")
+    parser.add_config_file_option(option_name="sign-tags", dest="sign_tags",
                       help="sign git tags", action="store_true")
-    parser.add_config_file_option(option_name="posttag", dest="posttag_hook",
+    parser.add_config_file_option(option_name="no-create-orig", dest="no_create_orig",
+                      help="don't create orig.tar.gz", action="store_true")
+    parser.add_config_file_option(option_name="posttag", dest="posttag",
                       help="hook to execute after a successfull tag operation")
     parser.add_config_file_option(option_name="keyid", dest="keyid",
                       help="GPG keyid to sign tags with")
     parser.add_config_file_option(option_name="debian-tag", dest="debian_tag",
-                      help="Format string for debian tags, default is '%(debian-tag)s'")
+                      help="format string for debian tags, default is '%(debian-tag)s'")
+    parser.add_config_file_option(option_name="upstream-tag", dest="upstream_tag",
+                      help="format string for upstream tags, default is '%(upstream-tag)s'")
+    parser.add_config_file_option(option_name="export-dir", dest="export_dir",
+                      help="before building export into EXPORT_DIR")
+    parser.add_option("--git-export", dest="treeish", default=default_tree,
+                      help="export treeish object TREEISH, default is '%s'" % default_tree)
     (options, args) = parser.parse_args(args)
 
     if options.verbose:
         Command.verbose = True
 
     try:
-        repo = GitRepository('.')
+        repo = GitRepository(os.path.curdir)
     except GitRepositoryError:
         print >>sys.stderr, "%s is not a git repository" % (os.path.abspath('.'))
         return 1
+    else:
+        repo_dir = os.path.abspath(os.path.curdir)
 
     try:
         if not options.ignore_new:
-            Command(options.clean_cmd, shell=True)()
+            Command(options.cleaner, shell=True)()
             (ret, out) = repo.is_clean()
             if not ret:
                 print >>sys.stderr, "You have uncommitted changes in your source tree:"
                 print >>sys.stderr, out
                 raise GbpError, "Use --git-ignore-new to ignore."
-        branch = repo.get_branch()
-        if branch != options.debian_branch and not options.ignore_new:
-            print >>sys.stderr, "You are not on branch '%s' but on '%s'" % (options.debian_branch, branch)
-            raise GbpError, "Use --git-ignore-new to ignore or --git-debian-branch to set the branch name."
+
+            branch = repo.get_branch()
+            if branch != options.debian_branch:
+                print >>sys.stderr, "You are not on branch '%s' but on '%s'" % (options.debian_branch, branch)
+                raise GbpError, "Use --git-ignore-new to ignore or --git-debian-branch to set the branch name."
 
         cp = parse_changelog(changelog)
         if not cp:
             raise GbpError,"'%s' does not exist, not a debian package" % changelog
-        if not is_native(cp) and not has_orig(cp, output_dir):
-            print "%s does not exist, creating from branch '%s'" % (orig_file(cp), options.upstream_branch)
-            if not repo.has_branch(options.upstream_branch):
-                raise GbpError, "Upstream branch '%s' does not exist" % options.upstream_branch
-            if not create_orig(cp, output_dir, options.upstream_branch):
-                raise GbpError
-
-        Command(options.build_cmd, [ '-i\.git/', '-I.git' ] + dpkg_args, shell=True)()
+
+        output_dir = prepare_output_dir(options.export_dir)
+        if not repo.has_treeish(options.treeish):
+            raise GbpError # git-ls-tree printed an error message already
+        # Export to another build dir if requested:
+        if options.export_dir:
+            tmp_dir = os.path.join(output_dir, "%s-tmp" % cp['Source'])
+            print "Exporting '%s' to '%s'" % (options.treeish, tmp_dir)
+            dump_tree(tmp_dir, options.treeish)
+            cp = parse_changelog(os.path.join(tmp_dir, 'debian', 'changelog'))
+            if is_native(cp):
+                version = cp['Debian-Version']
+            else:
+                version = cp['Upstream-Version']
+            export_dir = os.path.join(output_dir, "%s-%s" % (cp['Source'], version))
+            print "Moving '%s' to '%s'" % (tmp_dir, export_dir)
+            move_old_export(export_dir)
+            os.rename(tmp_dir, export_dir)
+
+        # Build the orig.tar.gz if necessary:
+        if not is_native(cp) and not has_orig(cp, output_dir) and not options.no_create_orig:
+            # --upstream-branch was given on the command line, so use this:
+            if options.upstream_branch != GbpOptionParser.defaults['upstream-branch']:
+                upstream_tree = options.upstream_branch
+            else:
+                upstream_tree = build_tag(options.upstream_tag, cp['Upstream-Version'])
+                # fall back to the upstream-branch tip if the tag doesn't exist
+                if not repo.has_treeish(upstream_tree):
+                    upstream_tree = GbpOptionParser.defaults['upstream-branch']
+            print "%s does not exist, creating from '%s'" % (orig_file(cp), upstream_tree)
+            if not repo.has_treeish(upstream_tree):
+                raise GbpError # git-ls-tree printed an error message already
+            if not create_orig(cp, output_dir, upstream_tree):
+                raise GbpError, "Cannot create upstream tarball at '%s'" % output_dir
+
+        if options.export_dir:
+            os.chdir(export_dir)
+
+        Command(options.builder, dpkg_args, shell=True)()
         if options.tag:
             try:
                 version = cp['Version']
             except KeyError:
                 raise GbpError, "Can't parse version from changelog"
             else:
-                print "Tagging", version
-                GitTag(options.sign_tag, options.keyid)(build_tag(options.debian_tag, version),
+                print "Tagging %s" % version
+                GitTag(options.sign_tags, options.keyid)(build_tag(options.debian_tag, version),
                        msg="Debian release %s" % version)
-                if(options.posttag_hook):
-                    Command(options.posttag_hook, shell=True)()
+                if(options.posttag):
+                    Command(options.posttag, shell=True)()
+
     except CommandExecFailed:
-        return 1
+        retval = 1
     except GbpError, err:
         if len(err.__str__()):
             print >>sys.stderr, err
-        return 1
-    return 0
+        retval = 1
+
+    if options.export_dir and not retval:
+        RemoveTree(export_dir)()
+
+    os.chdir(repo_dir)
+    return retval
 
 if __name__ == '__main__':
     sys.exit(main(sys.argv))
 
-# vim:et:ts=4:sw=4:
+# vim:et:ts=4:sw=4:et:sts=4:ai:set list listchars=tab\:»·,trail\:·:
diff --git a/git-dch b/git-dch
new file mode 100755
index 00000000..b98ce378
--- /dev/null
+++ b/git-dch
@@ -0,0 +1,270 @@
+#!/usr/bin/python
+# vim: set fileencoding=utf-8 :
+#
+# (C) 2007 Guido Guenther <agx@sigxcpu.org>
+#    This program is free software; you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation; either version 2 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program; if not, write to the Free Software
+#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+"""Generate Debian changelog entries from git changelogs"""
+
+import sys
+import re
+import os.path
+import shutil
+import subprocess
+import gbp.command_wrappers as gbpc
+from gbp.git_utils import (GitRepositoryError, GitRepository, build_tag)
+from gbp.config import GbpOptionParser
+from gbp.errors import GbpError
+from gbp.deb_utils import parse_changelog
+from gbp.command_wrappers import (Command, CommandExecFailed)
+
+snapshot_re = "\s*\*\* SNAPSHOT build @(?P<commit>[a-z0-9]+)\s+\*\*"
+
+def get_log(start, end, options, paths):
+    """Get the shortlog from commit 'start' to commit 'end'"""
+    try:
+        p1 = subprocess.Popen("git-log %s %s...%s -- %s" % (options, start, end, paths), shell=True,
+                              stdout=subprocess.PIPE)
+        p2 = subprocess.Popen(["git-shortlog"], stdin=p1.stdout, stdout=subprocess.PIPE)
+        changes = p2.communicate()[0].split('\n')
+    except OSError, err:
+        raise GbpError, "Cannot get changes: %s" % err
+    except ValueError, err:
+        raise GbpError, "Cannot get changes: %s" % err
+    if p1.wait() or p2.wait():
+        raise GbpError, "Cannot get changes, use --since."
+    return changes
+
+
+def system(cmd):
+    try:
+        Command(cmd, shell=True)()
+    except CommandExecFailed:
+        raise GbpError
+
+
+def add_changelog_entry(msg, author):
+    "add aa single changelog entry"
+    cmd = """DEBFULLNAME="%s" dch --append -- "%s" """ % (author, msg.replace('"','\\\"'))
+    system(cmd)
+
+
+def add_changelog_section(msg, distribution):
+    "add a new changelog section"
+    cmd = "dch --distribution=%s -i %s" % (distribution, msg)
+    system(cmd)
+
+def fixup_trailer():
+    """fixup the changelog trailer's comitter and email address - it might
+    otherwise point to the last git committer instead of the person creating
+    the changelog"""
+    cmd = "dch \"\""
+    system(cmd)
+
+def head_commit():
+    """get the full sha1 of the last commit on HEAD"""
+    commit = subprocess.Popen([ 'git-log', 'HEAD^..' ], stdout=subprocess.PIPE).stdout
+    sha = commit.readline().split()[-1]
+    return sha
+
+
+def snapshot_version(version):
+    """
+    get the current release and snapshot version
+    Format is <debian-version>~<release>.gbp<short-commit-id>
+    """
+    try:
+        (release, suffix) = version.rsplit('~', 1)
+        (snapshot, commit)  = suffix.split('.', 1)
+        if not commit.startswith('gbp'):
+            raise ValueError
+        else:
+            snapshot = int(snapshot)
+    except ValueError: # not a snapshot release
+        release = version
+        snapshot = 0
+    return release, snapshot
+
+
+def mangle_changelog(changelog, cp, snapshot, sha='unknown'):
+    """Mangle changelog to either add or remove snapshot markers"""
+    try:
+        tmp = '%s.%s' % (changelog, str(snapshot))
+        cw = file(tmp, 'w')
+        cr = file(changelog, 'r')
+        cr.readline() # skip version and empty line
+        cr.readline()
+        print >>cw, "%(Source)s (%(MangledVersion)s) %(Distribution)s; urgency=%(urgency)s\n" % cp
+
+        line = cr.readline()
+        if re.match(snapshot_re, line):
+            cr.readline() # consume the empty line
+            line = ''
+
+        if snapshot:
+            print >>cw, "  ** SNAPSHOT build @%s **\n" % sha
+
+        if line:
+            print >>cw, line.rstrip()
+        shutil.copyfileobj(cr, cw)
+        cw.close()
+        cr.close()
+        os.unlink(changelog)
+        os.rename(tmp, changelog)
+    except OSError, e:
+        raise GbpError, "Error mangling changelog %s" % e
+
+
+def do_release(changelog, cp):
+    "remove the snapshot header and set the distribution"
+    (release, snapshot) = snapshot_version(cp['Version'])
+    if snapshot:
+        cp['MangledVersion'] = release
+        mangle_changelog(changelog, cp, 0)
+    cmd = "dch --release"
+    system(cmd)
+
+
+def do_snapshot(changelog, next_snapshot):
+    """
+    Add new snapshot banner to most recent changelog section. The next snapshot
+    number is calculated by eval()'ing next_snapshot
+    """
+    commit = head_commit()
+
+    cp = parse_changelog(changelog)
+    (release, snapshot) = snapshot_version(cp['Version'])
+    snapshot = int(eval(next_snapshot))
+
+    suffix = "%d.gbp%s" % (snapshot, "".join(commit[0:6]))
+    cp['MangledVersion'] = "%s~%s" % (release, suffix)
+
+    mangle_changelog(changelog, cp, snapshot, commit)
+    return snapshot, commit
+
+
+def shortlog_to_dch(changes):
+    """convert the changes in git shortlog format to debian changelog format"""    
+    commit_re = re.compile('\s+(?P<msg>.*)')
+    author_re = re.compile('(?P<author>.*) \([0-9]+\)')
+    author = 'Unknown'
+
+    for line in changes:
+        r = commit_re.match(line)
+        msg = ''
+        if r:
+            msg = r.group('msg')
+        else:
+            r = author_re.match(line)
+            if r:
+                author = r.group('author')
+            elif line:
+                print >>sys.stderr, "Unknown changelog line: %s" % line
+        if msg:
+            add_changelog_entry(msg, author)
+
+
+def guess_snapshot_commit(cp):
+    """guess the last commit documented in the changelog from the snapshot banner"""
+    sr = re.search(snapshot_re, cp['Changes'])
+    if sr:
+        return sr.group('commit')
+
+
+def main(argv):
+    ret = 0
+    changelog = 'debian/changelog'
+    until = 'HEAD'
+
+    parser = GbpOptionParser(command=os.path.basename(argv[0]), prefix='',
+                             usage='%prog [options] paths')
+
+    parser.add_config_file_option(option_name="debian-branch", dest='debian_branch',
+                      help="branch the debian patch is being developed on, default is '%(debian-branch)s'")
+    parser.add_config_file_option(option_name="debian-tag", dest="debian_tag",
+                      help="Format string for debian tags, default is '%(debian-tag)s'")
+    parser.add_config_file_option(option_name="snapshot-number", dest="snapshot_number",
+                      help="Expression to determine the next snapshot number, default is '%(snapshot-number)s'")
+    parser.add_config_file_option(option_name="git-log", dest="git_log",
+                      help="options to pass to git-log, default is '%(git-log)s'")
+    parser.add_option("-v", "--verbose", action="store_true", dest="verbose", default=False,
+                      help="verbose command execution")
+    parser.add_option("-s", "--since", dest="since", help="commit to start from")
+    parser.add_option("-R", "--release", action="store_true", dest="release", default=False,
+                      help="mark as release")
+    parser.add_option("-S", "--snapshot", action="store_true", dest="snapshot", default=False,
+                      help="mark as snapshot build")
+    parser.add_option("-a", "--auto", action="store_true", dest="auto", default=False,
+                      help="autocomplete changelog from last snapshot or tag")
+    (options, args) = parser.parse_args(argv[1:])
+
+    if options.snapshot and options.release:
+        parser.error("--snapshot and --release are incompatible options")
+
+    try:
+        if options.verbose:
+            gbpc.Command.verbose = True
+
+        try:
+            repo = GitRepository('.')
+        except GitRepositoryError:
+            raise GbpError, "%s is not a git repository" % (os.path.abspath('.'))
+
+        branch = repo.get_branch()
+        if options.debian_branch != branch:
+            print >>sys.stderr, "You are not on branch '%s' but on '%s'" % (options.debian_branch, branch)
+            raise GbpError, "Use --debian-branch to set the branch to pick changes from"
+
+        cp = parse_changelog(changelog)
+
+        if options.since:
+            since = options.since
+        else:
+            since = ''
+            if options.auto:
+                since = guess_snapshot_commit(cp)
+                if since:
+                    print "Continuing from commit '%s'" % since
+                else:
+                    print "Couldn't get snapshot header, using version info"
+            if not since:
+                since = build_tag(options.debian_tag, cp['Version'])
+
+        if args:
+            print "Only looking for changes on '%s'" % " ".join(args)
+        changes = get_log(since, until, options.git_log, " ".join(args))
+        if changes:
+            if cp['Distribution'] != "UNRELEASED":
+                add_changelog_section(distribution="UNRELEASED", msg="UNRELEASED")
+            shortlog_to_dch(changes)
+            fixup_trailer()
+            if options.snapshot:
+                (snap, version) = do_snapshot(changelog, options.snapshot_number)
+                print "Changelog has been prepared for snapshot #%d at %s" % (snap, version)
+        else:
+            print "No changes detected from %s to %s." % (since, until)
+        if options.release:
+            do_release(changelog, cp)
+
+    except GbpError, err:
+        if len(err.__str__()):
+            print >>sys.stderr, err
+        ret = 1
+    return ret
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))
+
+# vim:et:ts=4:sw=4:et:sts=4:ai:set list listchars=tab\:»·,trail\:·:
diff --git a/git-import-dsc b/git-import-dsc
index 432c1556..51ce56a8 100755
--- a/git-import-dsc
+++ b/git-import-dsc
@@ -59,7 +59,7 @@ class DscFile(object):
                 self.tgz = os.path.join(fromdir, m.group('tar'))
                 continue
         f.close()
-    
+
 
 def parse_dsc(dscfile):
     """parse dsc by creating a DscFile object"""
@@ -91,7 +91,7 @@ def import_initial(src, dirs, options, tagger, filter):
         unpackTGZ = gbpc.UnpackTarArchive(src.tgz, dirs['tmp'], filter=filter)
         unpackTGZ()
     except gbpc.CommandExecFailed:
-        print >>sys.stderr, "Unpacking of %s failed" % src.archive
+        print >>sys.stderr, "Unpacking of %s failed" % src.tgz
         gbpc.RemoveTree(dirs['tmp'])()
         return False
 
@@ -155,6 +155,17 @@ def move_tree(src, dirs):
     return True
 
 
+def create_debian_branch(debian_branch, dirs):
+    os.chdir(dirs['git'])
+    repo = GitRepository('.')
+    if repo.get_branch() != debian_branch:
+        if not repo.has_branch(debian_branch):
+            print "Creating Debian branch '%s'" % debian_branch
+            gbpc.GitBranch()(debian_branch)
+        gbpc.GitCheckoutBranch(debian_branch)
+    os.chdir(dirs['top'])
+
+
 def main(argv):
     dirs = {'top': os.path.abspath(os.curdir)}
     ret = 0
@@ -164,6 +175,8 @@ def main(argv):
 
     parser.add_option("-v", "--verbose", action="store_true", dest="verbose", default=False,
                       help="verbose command execution")
+    parser.add_config_file_option(option_name="debian-branch", dest='debian_branch',
+                      help="branch the debian patch is being developed on, default is '%(debian-branch)s'")
     parser.add_config_file_option(option_name="upstream-branch", dest="upstream_branch",
                       help="upstream branch, default is '%(upstream-branch)s'")
     parser.add_config_file_option(option_name="sign-tags", dest="sign_tags",
@@ -203,6 +216,7 @@ def main(argv):
                                                 "%s-%s-%s" % (src.pkg, src.upstream_version, src.debian_version))
                 if not apply_debian_patch(src, dirs, options, gitTag, options.filter):
                     raise GbpError
+                create_debian_branch(options.debian_branch, dirs)
             os.chdir(dirs['top'])
             if not move_tree(src, dirs):
                 raise GbpError
@@ -210,11 +224,12 @@ def main(argv):
         if len(err.__str__()):
             print >>sys.stderr, err
         ret = 1
+        os.chdir(dirs['top'])
 
         if not ret:
             print 'Everything imported under %s' % src.pkg
 
 if __name__ == '__main__':
     sys.exit(main(sys.argv))
-	    
-# vim:et:ts=4:sw=4:
+
+# vim:et:ts=4:sw=4:et:sts=4:ai:set list listchars=tab\:»·,trail\:·:
diff --git a/git-import-orig b/git-import-orig
index ee986beb..145bc34a 100755
--- a/git-import-orig
+++ b/git-import-orig
@@ -50,7 +50,7 @@ def unpack_orig(archive, tmpdir):
     return unpackArchive.dir
 
 
-def import_source_tree(repo, orig_dir, version, upstream, filter):
+def import_source_tree(repo, orig_dir, version, filter):
     """import source tree to the current branch"""
     try:
         old = set(repo.index_files())
@@ -67,12 +67,22 @@ def import_source_tree(repo, orig_dir, version, upstream, filter):
         raise GbpError, "Import of new upstream version failed."
 
 
-def get_version(tgz):
-    """get the version from the filename of a .orig.tar.gz"""
-    origre = re.compile('^[a-z\d-]+_(?P<version>[a-z\d\.\~\-]+)\.orig\.tar\.gz')
-    m = origre.match(os.path.basename(tgz))
-    if m:
-        return m.group('version')    
+def guess_version(archive, version_regex=r''):
+    """
+    guess the version from the filename of an upstgream archive
+    @archive: filename to guess to version for
+    @version_regex: additional version regex to apply, needs a 'version' group
+    """
+    version_filters = [ # Debian package_<version>.orig.tar.gz:
+                        r'^[a-z\d\-]+_(?P<version>[a-z\d\.\~\-]+)\.orig\.tar\.(gz|bz2)',
+                        # Upstream package-<version>.tar.gz:
+                        r'^[a-z\d\-]+-(?P<version>[a-z\d\.]+)\.tar\.(gz|bz2)' ]
+    if version_regex:
+        version_filters = version_regex + version_filters
+    for filter in version_filters:
+        m = re.match(filter, os.path.basename(archive))
+        if m:
+            return m.group('version')
 
 
 def main(argv):
@@ -88,9 +98,9 @@ def main(argv):
                       help="verbose command execution")
     parser.add_option("--no-merge", dest='merge', action="store_false", default=True,
                       help="after import dont do any merging to another branch")
-    parser.add_config_file_option(option_name="debian-branch", dest='debian',
+    parser.add_config_file_option(option_name="debian-branch", dest='debian_branch',
                       help="branch the debian patch is being developed on, default is '%(debian-branch)s'")
-    parser.add_config_file_option(option_name="upstream-branch", dest="upstream",
+    parser.add_config_file_option(option_name="upstream-branch", dest="upstream_branch",
                       help="upstream branch, default is '%(upstream-branch)s'")
     parser.add_config_file_option(option_name="sign-tags", dest="sign_tags",
                       help="sign git tags", action="store_true")
@@ -102,9 +112,9 @@ def main(argv):
                       help="files to filter out during import")
     (options, args) = parser.parse_args(argv[1:])
 
-    gitCheckoutMaster = gbpc.GitCheckoutBranch(options.debian)
+    gitCheckoutMaster = gbpc.GitCheckoutBranch(options.debian_branch)
     gitShowBranch = gbpc.GitShowBranch()
-    gitPullUpstream = gbpc.GitPull('.', options.upstream)
+    gitPullUpstream = gbpc.GitPull('.', options.upstream_branch)
 
     try:
         if options.verbose:
@@ -126,19 +136,19 @@ def main(argv):
             is_empty = False
         else:
             is_empty = True
-    
-        if not repo.has_branch(options.upstream) and not is_empty:
+
+        if not repo.has_branch(options.upstream_branch) and not is_empty:
             print >>sys.stderr, """
 Repository does not have branch '%s' for upstream sources. If there is none see
 /usr/share/doc/git-buildpackage/manual-html/gbpc.import.convert.html on howto
 create it otherwise use --upstream-branch to specify it.
-"""  % options.upstream
+"""  % options.upstream_branch
             raise GbpError
 
         if options.version:
             version = options.version
         else:
-            version = get_version(archive)
+            version = guess_version(archive)
 
         if version:
             print "Upstream version is %s" % version
@@ -163,16 +173,19 @@ create it otherwise use --upstream-branch to specify it.
 
         try:
             if not is_empty:
-                print "Importing '%s' to branch '%s'..." % (archive, options.upstream)
-                gbpc.GitCheckoutBranch(options.upstream)()
+                print "Importing '%s' to branch '%s'..." % (archive, options.upstream_branch)
+                gbpc.GitCheckoutBranch(options.upstream_branch)()
             else:
                 print "Initial import of '%s'..." % archive
-            import_source_tree(repo, orig_dir, version, options.upstream, options.filter)
+
+            import_source_tree(repo, orig_dir, version, options.filter)
             gbpc.GitTag(options.sign_tags, options.keyid)(build_tag(options.upstream_tag, version),
                         msg="Upstream version %s" % version)
-       
-            if options.merge and not is_empty:
-                print "Merging to %s" % options.debian
+
+            if is_empty:
+                gbpc.GitBranch()(options.upstream_branch)
+            elif options.merge:
+                print "Merging to %s" % options.debian_branch
                 gitCheckoutMaster()
                 gitShowBranch()
                 try:
@@ -197,4 +210,4 @@ create it otherwise use --upstream-branch to specify it.
 if __name__ == "__main__":
     sys.exit(main(sys.argv))
 
-# vim:et:ts=4:sw=4:
+# vim:et:ts=4:sw=4:et:sts=4:ai:set list listchars=tab\:»·,trail\:·:
diff --git a/setup.py b/setup.py
index b8e373cf..14adcb1a 100644
--- a/setup.py
+++ b/setup.py
@@ -21,7 +21,7 @@ from distutils.core import setup
 setup(name = "git_build_package",
       author = 'Guido Guenther',
       author_email = 'agx@sigxcpu.org',
-      scripts = [ 'git-buildpackage', 'git-import-dsc', 'git-import-orig'],
+      scripts = [ 'git-buildpackage', 'git-import-dsc', 'git-import-orig', 'git-dch' ],
       packages = [ 'gbp' ],
       data_files = [("/etc/git-buildpackage/", ["gbp.conf" ]),],
 )