summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--debian/changelog6
-rw-r--r--debian/docs1
-rw-r--r--debian/links1
-rwxr-xr-xdebian/rules10
-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
-rw-r--r--docs/common.ent9
-rw-r--r--docs/copyright.sgml22
-rw-r--r--docs/manpages/git-buildpackage.sgml8
-rw-r--r--docs/manpages/git-import-dsc.sgml3
-rw-r--r--docs/manpages/git-import-orig.sgml11
-rw-r--r--docs/manpages/manpages.ent6
-rw-r--r--docs/manual.sgml38
16 files changed, 332 insertions, 16 deletions
diff --git a/debian/changelog b/debian/changelog
index 280f333f..19e961ea 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+git-buildpackage (0.2.20) unstable; urgency=low
+
+ * add some more documentation
+
+ -- Guido Guenther <agx@sigxcpu.org> Fri, 22 Dec 2006 15:05:09 +0100
+
git-buildpackage (0.2.19) unstable; urgency=low
* git-buildpackage: add an option (--git-cleaner) that allows to specify
diff --git a/debian/docs b/debian/docs
index e845566c..7fdec518 100644
--- a/debian/docs
+++ b/debian/docs
@@ -1 +1,2 @@
README
+docs/manual-html/
diff --git a/debian/links b/debian/links
new file mode 100644
index 00000000..803c8fee
--- /dev/null
+++ b/debian/links
@@ -0,0 +1 @@
+/usr/share/doc/git-buildpackage/manual-html/gbp.html /usr/share/doc/git-buildpackage/manual-html/index.html
diff --git a/debian/rules b/debian/rules
index 6ea935f3..4cea6597 100755
--- a/debian/rules
+++ b/debian/rules
@@ -9,17 +9,23 @@ include /usr/share/cdbs/1/class/python-distutils.mk
COMMANDS=git-buildpackage git-import-dsc git-import-orig
MANPAGES=$(patsubst %,docs/%.1,$(COMMANDS))
+MANUAL=docs/manual-html
PYCHECKS=$(patsubst %,%.py,$(COMMANDS))
PYCHECK_LEVEL=Error
docs/%.1: docs/man.%.sgml
docbook-to-man $< > $@
+$(MANUAL): docs/manual.sgml docs/chapters/*.sgml docs/manpages/*.sgml
+ docbook-2-html -s gtk $<
+
%.py: %
ln -s $< $@
PYTHONPATH=. pychecker -e $(PYCHECK_LEVEL) -q $<
-build/git-buildpackage:: $(MANPAGES) $(PYCHECKS)
+build/git-buildpackage:: $(MANPAGES) $(MANUAL) $(PYCHECKS)
clean::
- -rm docs/*.1 git-*.py
+ -rm docs/*.1 git-*.py
+ -rm -rf docs/manual-html/
+
diff --git a/docs/chapters/building.sgml b/docs/chapters/building.sgml
new file mode 100644
index 00000000..6cba1aeb
--- /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 00000000..eaa7e712
--- /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 00000000..7e54ed58
--- /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 00000000..b1fb35e2
--- /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 00000000..03de2ec1
--- /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>
diff --git a/docs/common.ent b/docs/common.ent
index f3f4fb64..f091df77 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -3,14 +3,21 @@
<!ENTITY dhdate "<date>2006-10-02</date>">
<!ENTITY dhsection "<manvolnum>1</manvolnum>">
<!ENTITY dhemail "<email>agx@sigxcpu.org</email>">
- <!ENTITY dhusername "&dhfirstname; &dhsurname">
+ <!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 gitcmd "<command>git</command>">
+ <!ENTITY gitkcmd "<command>gitk</command>">
+ <!ENTITY pbuildercmd "<command>pbuilder</command>">
+ <!ENTITY pdebuildcmd "<command>pdebuild</command>">
+ <!ENTITY debuildcmd "<command>debuild</command>">
<!ENTITY debian "<productname>Debian</productname>">
<!ENTITY git "<productname>Git</productname>">
+ <!ENTITY pbuilder "<productname>Pbuilder</productname>">
+ <!ENTITY debuild "<productname>Debuild</productname>">
+ <!ENTITY dpkg-buildpackage "<productname>Dpkg-buildpackage</productname>">
<!ENTITY gnu "<acronym>GNU</acronym>">
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>">
diff --git a/docs/copyright.sgml b/docs/copyright.sgml
new file mode 100644
index 00000000..f9ea8515
--- /dev/null
+++ b/docs/copyright.sgml
@@ -0,0 +1,22 @@
+ <para>
+ git-buildpackage, all associated scripts and programs, this manual,
+ and all build scripts are Copyright &copy; 2006 Guido Guenther.
+ </para>
+ <para>
+ 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; Version 2 of the License.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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
+ </para>
diff --git a/docs/manpages/git-buildpackage.sgml b/docs/manpages/git-buildpackage.sgml
index 70c1dfda..a221f906 100644
--- a/docs/manpages/git-buildpackage.sgml
+++ b/docs/manpages/git-buildpackage.sgml
@@ -106,7 +106,7 @@
<term><option>--git-upstream-branch</option>=<replaceable>branch_name</replaceable>
</term>
<listitem>
- <para>Branch to build the orig.tar.gz from. Default is 'upstream'</para>
+ <para>Branch to build the orig.tar.gz from. Default is <replaceable>upstream</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
@@ -114,8 +114,8 @@
</term>
<listitem>
<para>If you're not on this branch when invoking &git-buildpackage;
- it will fail. Default is 'master'. This option will be ignored
- when using <option>--git-ignore-new</option>.
+ it will fail. Default is <replaceable>master</replaceable>. This
+ option will be ignored when using <option>--git-ignore-new</option>.
</para>
</listitem>
</varlistentry>
@@ -123,7 +123,7 @@
</refsect1>
<refsect1>
&man.git.config-files;
- <para>All options in the config files are specified without the 'git-' prefix.
+ <para>All options in the config files are specified without the 'git-' prefix.</para>
<refsect1>
<title>SEE ALSO</title>
diff --git a/docs/manpages/git-import-dsc.sgml b/docs/manpages/git-import-dsc.sgml
index 42c0fa7e..656f6498 100644
--- a/docs/manpages/git-import-dsc.sgml
+++ b/docs/manpages/git-import-dsc.sgml
@@ -50,7 +50,8 @@
<term><option>--upstream-branch</option>=<replaceable>branch_name</replaceable>
</term>
<listitem>
- <para>The branch in the Git repository the upstream sources are put onto. Default is 'upstream'</para>
+ <para>The branch in the Git repository the upstream sources are put
+ onto. Default is <replaceable>upstream</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/docs/manpages/git-import-orig.sgml b/docs/manpages/git-import-orig.sgml
index 7bc169a7..979bf61a 100644
--- a/docs/manpages/git-import-orig.sgml
+++ b/docs/manpages/git-import-orig.sgml
@@ -39,7 +39,7 @@
<title>DESCRIPTION</title>
<para>
&git-import-orig; imports a tar.gz file given by
- <replaceable>tar_gz<replaceable> into the git-buildpackage repository. If
+ <replaceable>tar_gz</replaceable> into the git-buildpackage repository. If
<replaceable>tar_gz</replaceable> is already of the form
package_version.orig.tar.gz, it reads the version information from the
tarball's filename otherwise it can be specified on the commandline.
@@ -64,7 +64,8 @@
<term><option>--upstream-branch</option>=<replaceable>branch_name</replaceable>
</term>
<listitem>
- <para>The branch in the Git repository the upstream sources are put onto. Default is 'upstream'</para>
+ <para>The branch in the Git repository the upstream sources are put
+ onto. Default is <replaceable>upstream</replaceable></para>
</listitem>
</varlistentry>
<varlistentry>
@@ -72,9 +73,9 @@
</term>
<listitem>
<para>The branch in the Git repository the Debian package is being
- developed on, default is 'master'. After importing the new sources on
- the upstream branch, &git-import-orig; will try to merge the new
- version onto this branch.</para>
+ developed on, default is <replaceable>master</replaceable>. After
+ importing the new sources on the upstream branch, &git-import-orig;
+ will try to merge the new version onto this branch.</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 43f2a241..3e4e2205 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -3,8 +3,8 @@
<!ENTITY man.git.buildpackage SYSTEM "git-buildpackage.sgml">
<!ENTITY man.git.config-files "
<title>CONFIGURATION FILES</title>
- Three configuration files are parsed to set defaults for the above
- commandline arguments:
+ <para> Three configuration files are parsed to set defaults for the above
+ commandline arguments: </para>
<variablelist>
<varlistentry>
<term>/etc/git-buildpacakge/gbp.conf</term>
@@ -20,5 +20,5 @@
</varlistentry>
</variablelist>
<para>
- See /etc/git-buildpacakge/gbp.conf for an example.
+ See /etc/git-buildpackage/gbp.conf for an example.
</para>">
diff --git a/docs/manual.sgml b/docs/manual.sgml
new file mode 100644
index 00000000..b3c5fd11
--- /dev/null
+++ b/docs/manual.sgml
@@ -0,0 +1,38 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+ <!ENTITY % COMMON SYSTEM "common.ent">
+ %COMMON;
+ <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+ %MANPAGES;
+ <!ENTITY % CHAPTERS SYSTEM "chapters/chapters.ent">
+ %CHAPTERS;
+ <!ENTITY gbp.copyright SYSTEM "copyright.sgml">
+]>
+
+<book id="gbp">
+ <bookinfo>
+ <title>Building Debian Packages with git-buildpackage</title>
+ <author>
+ &dhfirstname; &dhsurname;
+ </author>
+ <address>&dhemail;</address>
+ </bookinfo>
+
+ &ch.intro;
+ &ch.import;
+<!---
+ &ch.building;
+-->
+ &ch.special;
+
+ <appendix id="gbp.man.reference">
+ <title>Command Reference</title>
+ &man.git.buildpackage;
+ &man.git.importdsc;
+ &man.git.importorig;
+ </appendix>
+ <appendix id="gbp.copyleft">
+ <title>Copyright</title>
+ &gbp.copyright;
+ </appendix>
+</book>
+
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-25 15:26:53 +0000