aboutsummaryrefslogtreecommitdiff
path: root/docs/chapters
diff options
context:
space:
mode:
authorGuido Guenther <agx@sigxcpu.org>2006-12-22 15:11:58 +0100
committerGuido Guenther <agx@bogon.sigxcpu.org>2006-12-22 15:11:58 +0100
commit2f3c8a58d8b7d75045244413b3a3db507c8d5b82 (patch)
tree2c1db18fecead41bc1ca5b29d2c6577bc18bfff9 /docs/chapters
parent69e776a291872d0b20f5a55527b68ea09996b920 (diff)
add some more documentation
some of the layout is based on what darcs-buildpackage does
Diffstat (limited to 'docs/chapters')
-rw-r--r--docs/chapters/building.sgml4
-rw-r--r--docs/chapters/chapters.ent5
-rw-r--r--docs/chapters/import.sgml69
-rw-r--r--docs/chapters/intro.sgml51
-rw-r--r--docs/chapters/special.sgml104
5 files changed, 233 insertions, 0 deletions
diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml
new file mode 100644
index 0000000..6cba1ae
--- /dev/null
+++ b/docs/chapters/building.sgml
@@ -0,0 +1,4 @@
+<chapter id="gbp.building">
+ <title>Building Packages from the &git; repository</title>
+ <para>TBD</para>
+</chapter>
diff --git a/docs/chapters/chapters.ent b/docs/chapters/chapters.ent
new file mode 100644
index 0000000..eaa7e71
--- /dev/null
+++ b/docs/chapters/chapters.ent
@@ -0,0 +1,5 @@
+<!ENTITY ch.intro SYSTEM "intro.sgml">
+<!ENTITY ch.workflow SYSTEM "workflow.sgml">
+<!ENTITY ch.import SYSTEM "import.sgml">
+<!ENTITY ch.building SYSTEM "building.sgml">
+<!ENTITY ch.special SYSTEM "special.sgml">
diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
new file mode 100644
index 0000000..7e54ed5
--- /dev/null
+++ b/docs/chapters/import.sgml
@@ -0,0 +1,69 @@
+<chapter id="gbp.import">
+ <title>Importing Sources</title>
+ <sect1 id="dbp.import.existing">
+ <title>Importing already existing &debian; packages</title>
+ <para>Imporing 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 <option>upstream</option>
+ branch and the debian patch on the <option>master</option> branch. In case
+ of a debian native package only the <option>master</option> branch is being
+ used.
+ </para>
+ </sect1>
+ <sect1 id="dbp.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 do:
+ <screen>
+&git-import-orig; /path/to/package_0.2.orig.tar.gz
+ </screen>
+ </para>
+ </sect1>
+ <sect1 id="dbp.import.convert">
+ <title>Converting an existing &git; repository</title>
+ <sect2>
+ <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:
+ <screen>
+mv .git/theupstream-branch .git/upstream
+ </screen>
+ or you can tell &git-buildpackage; the name of the branch:
+ <screen>
+cat &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>.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Upstream sources not on a branch</title>
+ <para>
+ If you don't have an upstream branch but started you repository with only
+ the upstream sources (not the debian patch) you can simply branch from that
+ point. So use &gitkcmd; or &gitcmd;-log to locate the commit-id of that commit
+ and create the upstream branch from there, e.g.:
+<screen>
+ COMMIT_ID=`&gitcmd; log --pretty=oneline | tail -1 | awk '{ print $1 }'`
+ &gitcmd; branch upstream $COMMIT_ID
+</screen>
+ The important thing here is that the <envar>COMMIT_ID</envar> specifies a
+ point on the master branch that carried <emphasis>only</emphasis> the
+ upstream sources and not the debian modifications. The above example
+ assumes that this was the first commit to that repository.
+ </para>
+ <warning><para>There's currently no easy way to use &git-import-orig; with
+ a repository that never had the upstream sources as a single commit. Using
+ it on such repositories might lead to unexpected merge results. You can use
+ <command>git_load_dirs</command> instead.</para></warning>
+ </sect2>
+ </sect1>
+</chapter>
diff --git a/docs/chapters/intro.sgml b/docs/chapters/intro.sgml
new file mode 100644
index 0000000..b1fb35e
--- /dev/null
+++ b/docs/chapters/intro.sgml
@@ -0,0 +1,51 @@
+<chapter id="gbp.intro">
+ <title>Introduction</title>
+ <para>
+ Welcome to &git-buildpackage;, a system that integrates the
+ <ulink url="http://www.debian.org/">Debian</ulink> package build
+ system with <ulink url="http://git.or.cz/">Git</ulink>.
+ </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>.
+ </para>
+</sect1>
+
+<sect1 id="gbp.workflow">
+ <title>Workflow</title>
+ <para>
+ A typical 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>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>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>
+ </orderedlist>
+ <para>These steps will be explaind in more details in the following sections.</para>
+</sect1>
+
+</chapter>
diff --git a/docs/chapters/special.sgml b/docs/chapters/special.sgml
new file mode 100644
index 0000000..03de2ec
--- /dev/null
+++ b/docs/chapters/special.sgml
@@ -0,0 +1,104 @@
+<chapter id="gbp.special">
+ <title>Special usage cases</title>
+ <sect1 id="dbp.special.dfsgfree">
+ <title>Handling non-DFSG clean upstream sources</title>
+ <para>If you have to handle non DFSG clean upstream sources you can use a
+ different branch which you have to create once:
+ <screen>
+&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:
+ </para>
+ <screen>
+&git-import-orig; --no-merge nondfsg-clean-package_10.4.orig.tar.gz
+&gitcmd; tag; 10.4
+ </screen>
+ <para>
+ After the import you can switch to the dfsg branch and get the newly
+ imported changes from the upstream branch:
+ </para>
+ <screen>
+&gitcmd; checkout dfsg_clean
+&gitcmd; pull . upstream
+ </screen>
+ <para>
+ Now make this dfsg clean (preverably by a cleanup script), commit your changes and merge to the master branch:
+ </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
+ </screen>
+
+ <sect1 id="dbp.special.nmus">
+ <title>Importing NMUs</title>
+ <para>
+ First create a branch that holds the NMUs once:
+ </para>
+ <screen>
+&gitcmd; <option>branch</option> <replaceable>nmu</replaceable>
+ </screen>
+ <para>
+ To import an NMU instead of a new upstream version you can use:
+ </para>
+ <screen>
+&gitcmd; checkout master
+&git-import-orig; -u 10-1.1 --upstream-branch=nmu nmu-10-1.1.tar.gz
+ </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.
+ </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="dbp.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
+ 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 "$*"
+EOF
+chmod a+x /usr/local/bin/git-pbuilder
+</programlisting>
+
+ Furthermore we need a different clean command, since &pdebuildcmd;
+ <option>clean</option> means something different than &debuildcmd;
+ <option>clean</option>. We could put all this on the command line, but
+ let's put it into the config file to safe typing:
+
+<programlisting>
+cat &lt;&lt;EOF &gt; <filename>~/.gbp.conf</filename>
+[DEFAULT]
+# tell git-buildpackage howto clean the source tree
+cleaner = fakeroot debian/rules clean
+# this is how we invoke pbuilder, arguments passed to git-buildpackage will be
+# passed to dpkg-buildpackge in the chroot
+builder = /usr/local/bin/git-pbuilder
+</programlisting>
+
+ Invoking &git-buildpackage; will now invoke &pdebuildcmd;</para>
+ <para>
+ If you don't want this for all your invocations of &git-buildpackage; you can instead
+ put this into <filename>.git/gbp.conf</filename> in one of your &git; repositories.
+ </para>
+
+</chapter>