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