path: root/docs/manpages/gbp-buildpackage.sgml

<refentry id="man.gbp.buildpackage">
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
  </refentryinfo>
  <refmeta>
    <refentrytitle>gbp-buildpackage</refentrytitle>
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>git-buildpackage</refname>
    <refname>gbp-buildpackage</refname>
    <refpurpose>Build Debian packages from a Git repository</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      &gbp-buildpackage;
      <arg><option>--git-[no-]ignore-new</option></arg>
      <arg><option>--git-tag</option></arg>
      <arg><option>--git-verbose</option></arg>
      <arg><option>--git-color=</option><replaceable>[auto|on|off]</replaceable></arg>
      <arg><option>--git-color-scheme</option>=<replaceable>COLOR_SCHEME</replaceable></arg>
      <arg><option>--git-notify=</option><replaceable>[auto|on|off]</replaceable></arg>
      <arg><option>--git-upstream-branch=</option><replaceable>treeish</replaceable></arg>
      <arg><option>--git-debian-branch=</option><replaceable>branch_name</replaceable></arg>
      <arg><option>--git-ignore-branch</option></arg>
      <arg><option>--git-builder=</option><replaceable>BUILD_CMD</replaceable></arg>
      <arg><option>--git-cleaner=</option><replaceable>CLEAN_CMD</replaceable></arg>
      <arg><option>--git-[no-]pbuilder</option></arg>
      <arg><option>--git-[no-]qemubuilder</option></arg>
      <arg><option>--git-dist=</option><replaceable>DIST</replaceable></arg>
      <arg><option>--git-arch=</option><replaceable>ARCH</replaceable></arg>
      <arg><option>--git-[no-]pbuilder-autoconf</option></arg>
      <arg><option>--git-pbuilder-options</option></arg>
      <arg><option>--git-[no-]sign-tags</option></arg>
      <arg><option>--git-keyid=</option><replaceable>gpg-keyid</replaceable></arg>
      <arg><option>--git-posttag=</option><replaceable>command</replaceable></arg>
      <arg><option>--git-postbuild=</option><replaceable>command</replaceable></arg>
      <arg><option>--git-postexport=</option><replaceable>command</replaceable></arg>
      <arg><option>--git-prebuild=</option><replaceable>command</replaceable></arg>
      <arg><option>--git-[no-]hooks</option></arg>
      <arg><option>--git-debian-tag=</option><replaceable>tag-format</replaceable></arg>
      <arg><option>--git-upstream-tag=</option><replaceable>tag-format</replaceable></arg>
      <arg><option>--git-force-create</option></arg>
      <arg><option>--git-no-create-orig</option></arg>
      <arg><option>--git-upstream-tree=</option><replaceable>[TAG|BRANCH|treeish]</replaceable></arg>
      <arg><option>--git-tarball-dir=</option><replaceable>directory</replaceable></arg>
      <arg><option>--git-compression=</option><replaceable>type</replaceable></arg>
      <arg><option>--git-compression-level=</option><replaceable>level</replaceable></arg>
      <arg><option>--git-export-dir=</option><replaceable>directory</replaceable></arg>
      <arg><option>--git-export=</option><replaceable>treeish</replaceable></arg>
      <arg><option>--git-[no-]pristine-tar</option></arg>
      <arg><option>--git-[no-]pristine-tar-commit</option></arg>
      <arg><option>--git-[no-]-purge</option></arg>
      <arg><option>--git-dont-purge</option></arg>
      <arg><option>--git-tag-only</option></arg>
      <arg><option>--git-retag</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
    &gbp-buildpackage; is used to build Debian source and .deb packages from a &git; repository.
    </para>
    <para>
        &gbp-buildpackage; will, in order:
   </para>
    <itemizedlist>
        <listitem><para>Verify that it is being executed from the
            proper location.</para>
        </listitem>
	<listitem><para>Verify that the repository doesn't contain any
	uncommitted source changes.</para>
	</listitem>
        <listitem><para>Verify that it is being executed from the
        correct branch.</para>
        </listitem>
	<listitem><para>
	(Optionally) export the source tree to a separate build area
	</para></listitem>
        <listitem><para>Build an orig tarball if it doesn't exist.</para>
        </listitem>
        <listitem><para>Call <application>debuild</application>(1)
            (or the application specified via <option>--git-builder</option>)
            with arguments instructing it to ignore &git; meta-data in
            the diff.gz, passing along all arguments given to
            &gbp-buildpackage; that don't start with --git-.
          </para>
        </listitem>
	<listitem><para>
	(Optionally) tag the tree after a successful build
	</para></listitem>
	<listitem><para>
	(Optionally) call a post build hook - e.g. to run &lintian;
	</para></listitem>
	<listitem><para>
	(Optionally) call a post tag hook - e.g. to push the results to a remote
	repository after creating the tag
	</para></listitem>
    </itemizedlist>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term><option>--git-[no-]ignore-new</option>
        </term>
        <listitem>
          <para>Don't abort if there are uncommitted changes in the source tree
          or the current branch doesn't match the
          <replaceable>debian-branch</replaceable>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-tag</option>
        </term>
        <listitem>
          <para>Add a git tag after a successful build.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-builder=<replaceable>BUILD_CMD</replaceable></option></term>
        <listitem>
          <para>Use <replaceable>BUILD_CMD</replaceable> instead of <command>debuild -i -I</command></para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-cleaner=<replaceable>CLEAN_CMD</replaceable></option></term>
        <listitem>
          <para>Use <replaceable>CLEAN_CMD</replaceable> instead of <command>debuild clean</command></para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-pbuilder</option></term>
        <listitem>
	  <para>Build package using <command>git-pbuilder</command>. Note that
	  this overwrites any <option>--git-builder</option> and
	  <option>--git-cleaner</option> options.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-qemubuilder</option></term>
        <listitem>
	  <para>Build package using <command>git-pbuilder</command> with
	  <command>qemubuilder</command>. Note that this overwrites any
	  <option>--git-builder</option> and <option>--git-cleaner</option>
	  options.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-dist=<replaceable>DIST</replaceable></option></term>
        <listitem>
	  <para>Build for distribution <replaceable>DIST</replaceable> when
	  using <command>--git-pbuilder</command>. If unset build for the
	  unstable distribution.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-arch=<replaceable>ARCH</replaceable></option></term>
        <listitem>
	  <para>Build for architecture <replaceable>ARCH</replaceable> when
	  using <command>--git-pbuilder</command>. If unset no architecture is
	  passed to <command>git-pbuilder</command>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-pbuilder-autoconf</option></term>
        <listitem>
	  <para>Whether to try to autoconfigure
	  <command>git-pbuilder</command> or to rely on the settings in
	  .pbuilderrc. See the <command>git-pbuilder</command>
          manpage for details.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-pbuilder-options</option></term>
        <listitem>
	  <para>Options to pass to pbuilder</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-verbose</option>
        </term>
        <listitem>
          <para>verbose execution</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-color=</option><replaceable>[auto|on|off]</replaceable>
        </term>
        <listitem>
          <para>Whether to use colored output.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-notify=</option><replaceable>[auto|on|off]</replaceable>
        </term>
        <listitem>
          <para>Whether to send a desktop notification after the build.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-color-scheme</option>=<replaceable>COLOR_SCHEME</replaceable></term>
        <listitem>
          <para>
          Colors to use in output (when color is enabled). The format for
          COLOR_SCHEME is
          '&lt;debug&gt;:&lt;info&gt;:&lt;warning&gt;:&lt;error&gt;'.
          Numerical values and color names are accepted, empty fields imply
          the default color. For example --git-color-scheme='cyan:34::' would
          show debug messages in cyan, info messages in blue and other messages
          in default (i.e. warning and error messages in red).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-upstream-branch</option>=<replaceable>branch_name</replaceable>
        </term>
        <listitem>
	  <para>Branch to build the orig tarball from if <option>--git-upstream-tree</option>
	  is set to <replaceable>BRANCH</replaceable>. Default is
	  <replaceable>upstream</replaceable>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-debian-branch</option>=<replaceable>branch_name</replaceable>
        </term>
        <listitem>
	  <para>If you're not on this branch when invoking &gbp-buildpackage;
	  it will fail. Default is <replaceable>master</replaceable>. This is
	  done to make sure you don't accidentally release from a topic branch.
	  Not being on this branch will be ignored when using
	  <option>--git-ignore-new</option>.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-ignore-branch</option>
        </term>
        <listitem>
            <para>Don't check if the current branch matches
            <replaceable>debian-branch</replaceable>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-[no-]sign-tags</option>
        </term>
        <listitem>
	  <para>GPG sign all created tags</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-keyid=</option><replaceable>gpg-keyid</replaceable>
        </term>
        <listitem>
	  <para>use this keyid for gpg signing tags</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-posttag=</option><replaceable>command</replaceable>
        </term>
        <listitem>
	  <para>excecute <replaceable>command</replaceable> after tagging a new
	  version.</para><para>Exported environment variables are:
	  <envar>GBP_TAG</envar> (the name of the generated tag),
	  <envar>GBP_BRANCH</envar> (the branch the package was build from) and
	  <envar>GBP_SHA1</envar> (the sha1 of the commit the tag was created
	  at).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-postbuild=</option><replaceable>command</replaceable>
        </term>
        <listitem>
	  <para>execute <replaceable>command</replaceable> after successful
	  build.</para><para> Exported environment variables are:
	  <envar>GBP_CHANGES_FILE</envar> (the name of the generated changes
	  file), <envar>GBP_BUILD_DIR</envar> (the build dir).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-postexport=</option><replaceable>command</replaceable>
        </term>
        <listitem>
	  <para>execute <replaceable>command</replaceable> after exporting the source
	  tree - valid only if --git-export-dir has been specified.</para>
	  <para> Exported environment variables are:
	  <envar>GBP_GIT_DIR</envar> (the repository the package is being built
	  from), <envar>GBP_TMP_DIR</envar> (the temporary directory where the
	  sources have been initially exported).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-prebuild=</option><replaceable>command</replaceable>
        </term>
        <listitem>
          <para>execute <replaceable>command</replaceable> from the build
          directory before calling <application>debuild</application>
          or the application specified via <option>--git-builder</option>.</para>
          <para>Exported environment variables are:
          <envar>GBP_GIT_DIR</envar> (the repository the package is being built from),
          <envar>GBP_BUILD_DIR</envar> (the build dir).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-[no-]hooks</option></term>
        <listitem>
      <para>Enable running all (cleaner, postexport, prebuild, postbuild,
      and posttag) hooks. Note: the <option>--git-builder</option> command is
      not affected by this option.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-debian-tag=</option><replaceable>tag-format</replaceable>
        </term>
        <listitem>
          <para>use this tag format when tagging Debian versions,
  	  default is <replaceable>debian/%(version)s</replaceable></para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-upstream-tag=</option><replaceable>tag-format</replaceable>
        </term>
        <listitem>
          <para>use this tag format when looking for tags of upstream versions,
  	  default is <replaceable>upstream/%(version)s</replaceable>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-force-create</option>
        </term>
        <listitem>
	  <para>Force creation of an orig tarball (overwriting a pre-existing one if present)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-no-create-orig</option>
        </term>
        <listitem>
	  <para>Don't try to create any orig tarball</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-overlay</option>
        </term>
        <listitem>
	  <para>Extract orig tarball when using export-dir option (analog to mergeWithUpstream in svn-bp)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-export-dir=</option><replaceable>directory</replaceable>
        </term>
        <listitem>
	  <para>Export the current branch head (or the treeish object given via
	  <option>--git-export</option> to <replaceable>directory</replaceable>
	  before building.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-export=</option><replaceable>treeish</replaceable>
        </term>
	<listitem> 
	  <para>Instead of exporting the current branch head, export the
	  treeish object <replaceable>treeish</replaceable>. The special name
	  <replaceable>INDEX</replaceable> exports the current index whereas
          the special name <replaceable>WC</replaceable> exports the current working
          copy as is.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-upstream-tree=</option><replaceable>[tag|branch]</replaceable>
        </term>
        <listitem>
	  <para>How to find the upstream sources used to generate the tarball.
	  <replaceable>TAG</replaceable> looks at a tag corresponding to the
	  version in the changelog. <replaceable>BRANCH</replaceable> looks at
	  the upstream branch given via the <option>--git-upstream-branch</option>
	  option. Other values are interpreted as treeishs.
	  </para><para>
	  This doesn't have any effect if <option>--git-pristine-tar</option>
	  is being used.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-tarball-dir=</option><replaceable>directory</replaceable>
        </term>
        <listitem>
          <para>Search for original tarballs in <replaceable>directory</replaceable> instead of generating them</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-compression=</option><replaceable>type</replaceable>
        </term>
        <listitem>
	  <para>Specifies the upstream tarball compression type. This will be
	  used to locate and build the upstream tarball if necessary. The
	  default is <replaceable>auto</replaceable> which derives the
	  compression type from the pristine-tar branch if available and falls
	  back to gzip otherwise. Other options are
	  <replaceable>gzip</replaceable>, <replaceable>bzip2</replaceable>, 
	  <replaceable>lzma</replaceable> and <replaceable>xz</replaceable>.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-compression-level=</option><replaceable>level</replaceable>
        </term>
        <listitem>
          <para>Specifies the upstream tarball compression level if an upstream tarball needs to be built.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git[-no]-purge</option>
        </term>
        <listitem>
	  <para>Purge (remove) temporary build directory after build</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-dont-purge</option>
        </term>
        <listitem>
	  <para>Deprecated, use --git-no-purge instead.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-tag-only</option>
        </term>
        <listitem>
	  <para>don't build, only tag and run post-tag hooks</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-retag</option>
        </term>
        <listitem>
	  <para>don't fail tag operations if a tag with the same version
	  already exists</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-pristine-tar</option>
        </term>
        <listitem>
	  <para>Use pristine-tar when generating the upstream tarball if it doesn't exist.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--git-pristine-tar-commit</option>
        </term>
        <listitem>
	  <para>Commit the pristine-tar delta to the pristine-tar branch if a new tarball was
          generated and the pristine-tar data isn't already there.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>EXAMPLES</title>
    <para>Build a Debian package using &git-pbuilder; which in turn invokes &cowbuildercmd;.
      Instruct cowbuilder to build within a Wheezy chroot for i386.</para>
    <screen>
      &gbp-buildpackage; --git-pbuilder --git-arch=i386 --git-dist=wheezy
    </screen>
    <para>
      Note that the above needs a &cowbuildercmd; chroot already. This can be created using:
    </para>
    <screen>
      DIST=wheezy ARCH=i386 &git-pbuilder; create
    </screen>
  </refsect1>
  <refsect1>
      &man.gbp.config-files;
      <para>All options in the config files are specified without the 'git-' prefix.</para>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <xref linkend="man.gbp.import.dsc">,
      <xref linkend="man.gbp.import.dscs">,
      <xref linkend="man.gbp.import.orig">,
      <xref linkend="man.gbp.dch">,
      <citerefentry>
        <refentrytitle>git-pbuilder</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>cowbuilder</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>,
      <xref linkend="man.gbp.conf">,
      &man.seealso.common;
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

    <para>&dhusername; &dhemail;</para>

  </refsect1>
</refentry>