<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 perfer 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>
