docs/chapters/cfgfile.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

<chapter id="gbp.cfgfile">
  <title>Configuration Files</title>
  <para>The configuration files are parsed in this order:
  <variablelist>
    <varlistentry>
      <term>/etc/git-buildpackage/gbp.conf</term>
      <listitem><para>system wide configuration</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>~/.gbp.conf</term>
      <listitem><para>per user configuration</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>.gbp.conf</term>
      <listitem><para>per repository/branch configuration (deprecated)</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>debian/gbp.conf</term>
      <listitem><para>per repository/branch configuration</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>.git/gbp.conf</term>
      <listitem><para>per (local) repository configuration</para></listitem>
    </varlistentry>
  </variablelist>
  All have the same format. They consist of several sections, all of them are optional:
  <variablelist>
    <varlistentry>
      <term>[DEFAULT]</term>
      <listitem>
	<para>Options in this section apply to all &gbp; commands.</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>[buildpackage]</term>
      <listitem><para>Options in this section apply to &gbp-buildpackage; only and override options from the
      [DEFAULT] section.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>[import-orig]</term>
      <listitem><para>Options in this section apply to &gbp-import-orig; only and override options from the
      [DEFAULT] section.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>[import-dsc]</term>
      <listitem><para>Options in this section apply to &gbp-import-dsc; only and override options from the
      [DEFAULT] section.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>[dch]</term>
      <listitem><para>Options in this section apply to &gbp-dch; only and override options from the
      [DEFAULT] section.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>...</term>
      <listitem><para>Same for the other &gbp; 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:
  </para>
  <screen>
    <option>upstream-branch</option>=<replaceable>dfsgfree</replaceable>
  </screen>
  <para>
    in the config file. In the special case of &gbp-buildpackage;, the stripped
    prefix is not '--' but '--git-'. Here's a more complete example:
  </para>
  <programlisting>
    [DEFAULT]
    # the default build command
    builder=debuild -i\.git -I.git
    # the default branch for upstream sources
    upstream-branch=upstream
    # the default branch for the debian patch
    debian-branch=master

    [buildpackage]
    upstream-branch=dfsgclean
    # Sign tags with GPG:
    sign-tags = True
    # Keyid to sign tags with
    #keyid = 0xdeadbeef

    [import-orig]
    upstream-branch=notdfsgclean

    [import-dsc]
    upstream-branch=notdfsgclean

    [dch]
    git-log=--no-merges
  </programlisting>
  <para>
    For more details, see the <xref linkend="man.gbp.conf"/> manual page.
  </para>

  <sect1 id="gbp.cfgfile.order">
    <title>Overriding Parsing Order</title>
    <para>
      The environment variable <envar>GBP_CONF_FILES</envar> can be
      used to override the order in which configuration files are
      parsed. The following example parses two configuration files in the
      users home directory (<filename>~/.gbp.conf</filename> and
      <filename>~/.gbp.late.conf</filename>) and in the debian
      directory (<filename>debian/gbp.conf</filename>).
      The file are parsed from left to right.  Since <filename>
      ~/.gbp.late.conf</filename> is at the very end of the list it
      can be used to override configuration entries shipped by the
      package. This can be useful if packages set
      e.g. <option>export-dir</option> or
      <option>tarball-dir</option> and you prefer different locations:
      <programlisting>
	$ cat &lt;&lt;EOF &gt;~/.gbp.late.conf
	[DEFAULT]
	export-dir = ../build-area
	tarball-dir = ../tarballs
	EOF

	$ export GBP_CONF_FILES=~/.gbp.conf:debian/gbp.conf:~/.gbp.late.conf
	$ cd  &lt;mypkg&gt;
	$ gbp config buildpackage.export-dir
	../build-area
      </programlisting>
    </para>
    <para>
      If you want all configuration files to be skipped, set
      <envar>GBP_CONF_FILES</envar> to a non existing location.  This way
      only default values and options from the command line will be used:
      <programlisting>
	$ export GBP_CONFI_FILES=/does/not/exist
	$ gbp config buildpackage.debian-branch
	master
      </programlisting>
    </para>
  </sect1>
</chapter>