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