aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGuido Günther <agx@sigxcpu.org>2012-03-08 08:57:20 +0100
committerGuido Günther <agx@sigxcpu.org>2012-03-08 13:56:21 +0100
commit80cf6d42a52bec3972da4f8b2bc388673f4681d4 (patch)
treed021a113e996b2507faeed5612b31bc3e5773b46
parent45d7dc8811377f69d321e31a4d30fb534ab0155d (diff)
Add manual page for gbp.conf
Closes: #661748 Thanks: Jari Alto for the POD version
-rw-r--r--docs/Makefile7
-rw-r--r--docs/chapters/cfgfile.sgml14
-rw-r--r--docs/common.ent1
-rw-r--r--docs/man.gbp.conf.sgml11
-rw-r--r--docs/manpages/gbp.conf.sgml225
-rw-r--r--docs/manpages/manpages.ent1
-rw-r--r--docs/manual.sgml1
7 files changed, 254 insertions, 6 deletions
diff --git a/docs/Makefile b/docs/Makefile
index 8772f47..b10ec10 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,6 +1,6 @@
#!/usr/bin/make
-COMMANDS = git-buildpackage \
+MANS = git-buildpackage \
git-import-dsc \
git-import-dscs \
git-import-orig \
@@ -8,10 +8,11 @@ COMMANDS = git-buildpackage \
gbp-pull \
gbp-clone \
gbp-pq \
- gbp-create-remote-repo
+ gbp-create-remote-repo \
+ gbp.conf
MANUAL=manual-html
-SGML_MANPAGES=$(patsubst %,%.1,$(COMMANDS))
+SGML_MANPAGES=$(patsubst %,%.1,$(MANS))
POD_MANPAGES=git-pbuilder.1
MANPAGES=$(SGML_MANPAGES) $(POD_MANPAGES)
VERSION_ENT=version.ent
diff --git a/docs/chapters/cfgfile.sgml b/docs/chapters/cfgfile.sgml
index d7c7a0d..fbff9e0 100644
--- a/docs/chapters/cfgfile.sgml
+++ b/docs/chapters/cfgfile.sgml
@@ -12,7 +12,7 @@
</varlistentry>
<varlistentry>
<term>.gbp.conf</term>
- <listitem><para>per repository/branch configuration</para></listitem>
+ <listitem><para>per repository/branch configuration (deprecated)</para></listitem>
</varlistentry>
<varlistentry>
<term>debian/gbp.conf</term>
@@ -23,7 +23,7 @@
<listitem><para>per (local) repository configuration</para></listitem>
</varlistentry>
</variablelist>
- All have the same format. They consist of (at most) five sections, all of them are optional:
+ All have the same format. They consist of several sections, all of them are optional:
<variablelist>
<varlistentry>
<term>[DEFAULT]</term>
@@ -50,14 +50,20 @@
<listitem><para>Options in this section apply to &git-dch; only and override options from the
[DEFAULT] section.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term>...</term>
+ <listitem><para>Same for the other <command>git-*</command> and <command>gbp-*</command> commands</para></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:
<screen>
<option>upstream-branch</option>=<replaceable>dfsgfree</replaceable>
</screen>
+<para>
in the config file. In the special case of &git-buildpackage; the stripped
prefix is not '--' but '--git-'. Here's a more complete example:
+</para>
<programlisting>
[DEFAULT]
# the default build command
@@ -83,5 +89,7 @@ upstream-branch=notdfsgclean
[git-dch]
git-log=--no-merges
</programlisting>
- </para>
+<para>
+For more details see the <xref linkend="gbp.man.gbp.conf"> manual page.
+</para>
</chapter>
diff --git a/docs/common.ent b/docs/common.ent
index 735511a..9c1b289 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -17,6 +17,7 @@
<!ENTITY pbuildercmd "<command>pbuilder</command>">
<!ENTITY pdebuildcmd "<command>pdebuild</command>">
<!ENTITY debuildcmd "<command>debuild</command>">
+ <!ENTITY gbp.conf "<filename>gbp.conf</filename>">
<!ENTITY debian "<productname>Debian</productname>">
<!ENTITY git "<productname>Git</productname>">
diff --git a/docs/man.gbp.conf.sgml b/docs/man.gbp.conf.sgml
new file mode 100644
index 0000000..c01433f
--- /dev/null
+++ b/docs/man.gbp.conf.sgml
@@ -0,0 +1,11 @@
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+ <!ENTITY % COMMON SYSTEM "common.ent">
+ %COMMON;
+ <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+ %MANPAGES;
+]>
+
+<reference>
+<title>gbp.conf Manual</title>
+&man.gbp.conf;
+</reference>
diff --git a/docs/manpages/gbp.conf.sgml b/docs/manpages/gbp.conf.sgml
new file mode 100644
index 0000000..d3f7d6a
--- /dev/null
+++ b/docs/manpages/gbp.conf.sgml
@@ -0,0 +1,225 @@
+<refentry id="gbp.man.gbp.conf">
+ <refentryinfo>
+ <address>
+ &dhemail;
+ </address>
+ <author>
+ &dhfirstname;
+ &dhsurname;
+ </author>
+ </refentryinfo>
+ <refmeta>
+ <refentrytitle>gbp.conf</refentrytitle>
+ &dhsection;
+ </refmeta>
+ <refnamediv>
+ <refname>&gbp.conf;</refname>
+ <refpurpose>git-buildpackage configuration file</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <variablelist>
+ <varlistentry>
+ <term>/etc/git-buildpackage/gbp.conf</term>
+ <listitem><para>system wide</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>~/.gbp.conf</term>
+ <listitem><para>per user</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>.gbp.conf</term>
+ <listitem><para>per branch, can be published with the
+ repository (deprecated)</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>debian/gbp.conf</term>
+ <listitem><para>per branch, can be published with the
+ repository</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>.git/gbp.conf</term>
+ <listitem><para>per repository</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>DESCRIPTION</title>
+ <para>
+ The <filename>gbp.conf</filename> provides default global options and specific options
+ for &git-buildpackage; commands. All have the same format and are parsed in the above order. The
+ file consists of several sections, one for each command. Comments start with a hash sign
+ (<option>#</option>). The generic file syntax is:
+ </para>
+<programlisting>
+ [DEFAULT]
+ # This is section for global settings. Affects all commands
+ key = value
+
+ [&lt;command&gt;]
+ # Specific sections for each command, like &git-buildpackage;
+ key = value
+</programlisting>
+
+<para>
+
+<option>key=value</option> pairs of the command sections reflect the command line
+options and their settings. For example <xref linkend="gbp.man.git.buildpackage">
+manualpage contains the <option>--git-export-dir</option>=<parameter>diirectory</parameter>
+option which can be turned into configuration file setting by dropping the
+<option>--git</option> prefix with:
+
+<programlisting>
+ [git-buildpackage]
+ export-dir = directory
+</programlisting>
+
+<para>
+Notice that some option are actually repeatable, or take Python lists.
+For example the <xref linkend="gbp.man.git.import.orig"> commmand has the
+<option>--filter</option>=<parameter>pattern</parameter> option which can
+be truned into a configuration file option like this:
+
+<programlisting>
+ [git-import-orig]
+ filter = .svn
+ filter = .hg
+</programlisting>
+
+<para>
+An alternative way is to write it using Python list syntax:
+</para>
+
+<programlisting>
+ [git-import-orig]
+ filter = [ '.svn', '.hg' ]
+</programlisting>
+
+<para>
+Boolean options can bei either <option>True</option> or <option>False</option>. For example
+<xref linkend="gbp.man.git.import.orig">; has the <option>--pristine-tar</option> and
+<option>--no-pristine-tar</option> options which translate to:
+</para>
+<programlisting>
+ [git-import-orig]
+ pristine-tar = True
+</programlisting>
+
+<para>and</para>
+
+<programlisting>
+ [git-import-orig]
+ pristine-tar = False
+</programlisting>
+<para>respectively.</para>
+
+ </refsect1>
+ <refsect1>
+ <title>EXAMPLES</title>
+<para>
+An example set up for packaging work:
+</para>
+
+<programlisting>
+ # $HOME/gbp.conf
+
+ [DEFAULT]
+ pristine-tar = True
+ cleaner = fakeroot debian/rules clean
+
+ [git-buildpackage]
+ export-dir = ../build-area/
+
+ [git-import-orig]
+ dch = False
+ filter = .svn
+ filter = .hg
+ filter = .bzr
+ filter = CVS
+ filter = debian/*
+ filter = */debian/*
+ filter-pristine-tar = True
+
+ [git-import-dsc]
+ filter = [
+ 'CVS',
+ '.cvsignore',
+ '.hg',
+ '.hgignore'
+ '.bzr',
+ '.bzrignore',
+ '.gitignore'
+ ]
+
+ # End of file
+</programlisting>
+
+<refsect1>
+ <title>FILES</title>
+<para>
+ See See <filename>/etc/git-buildpackage/gbp.conf</filename> for an example.
+</para>
+</refsect1>
+
+<refsect1>
+ <title>STANDARDS</title>
+<para>
+ The at <ulink url="file:///usr/share/doc/git-buildpackage/manual-html/index.html">
+ <citetitle>The Git-Buildpackage Manual</citetitle></ulink> at
+ <filename>/usr/share/doc/git-buildpackage/manual-html/index.html</filename>
+</para>
+</refsect1>
+
+<refsect1>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>gbp-clone</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>gbp-create-remote-repo</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>gbp-pq</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>gbp-pull</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>git-dch</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>git-import-dsc</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>git-import-dscs</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>git-import-orig</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>git-pbuilder</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>git-buildpackage</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>,
+ </para>
+</refsect1>
+<refsect1>
+ <title>AUTHORS</title>
+ <para>&dhusername; &dhemail;</para>
+ <para>This manual page is based on a POD version by Jari Aalto <email>jari.aalto@cante.net</email>.
+ Released under license GNU GPL version 2 or (at your option) any later.
+ version.
+ </para>
+ </refsect1>
+</refentry>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index be577db..058b66d 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -7,5 +7,6 @@
<!ENTITY man.gbp.clone SYSTEM "gbp-clone.sgml">
<!ENTITY man.gbp.pq SYSTEM "gbp-pq.sgml">
<!ENTITY man.gbp.create.remote.repo SYSTEM "gbp-create-remote-repo.sgml">
+<!ENTITY man.gbp.conf SYSTEM "gbp.conf.sgml">
<!ENTITY man.git.config-files SYSTEM "man.conffiles.sgml">
<!ENTITY man.seealso.common SYSTEM "man.seealso.sgml">
diff --git a/docs/manual.sgml b/docs/manual.sgml
index 3e3add8..4b9026f 100644
--- a/docs/manual.sgml
+++ b/docs/manual.sgml
@@ -36,6 +36,7 @@
&man.gbp.pull;
&man.gbp.pq;
&man.gbp.create.remote.repo;
+ &man.gbp.conf;
</appendix>
<appendix id="gbp.copyleft">
<title>Copyright</title>