1 files changed, 49 insertions, 6 deletions
diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
index 2522b8be..2c05e5dd 100644
@@ -183,7 +183,7 @@ EOF
<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.
+ <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>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>.
+ git clone --no-checkout -o upstream git://git.example.com/libgbp.git
+ cd libgbp
+ git checkout -b debian/sid v1.0
+ 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:
+ gbp buildpackage --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid
+ 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:
+ 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'
+ 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:
+ 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
+ If you want to share you're repository with others you can use &gbp-create-remote-repo; and &gbp-pull; as usual.