<refentry id="gbp.man.gbp.pq">
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
  </refentryinfo>
  <refmeta>
   <refentrytitle>gbp-pq</refentrytitle>
    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&gbp-pq;</refname>

    <refpurpose>Manage quilt patches on patch queue branches in git</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      &gbp-pq;
      <arg><option>--verbose</option></arg>
      <arg><option>--color=</option><replaceable>[auto|on|off]</replaceable></arg>
      <arg><option>--[no-]patch-numbers</option></arg>
      <arg><option>--topic=</option><replaceable>topic</replaceable></arg>
      <arg><option>--time-machine=</option><replaceable>num</replaceable></arg>
      <group choice="plain">
      <arg><option>export</option></arg>
      <arg><option>import</option></arg>
      <arg><option>rebase</option></arg>
      <arg><option>drop</option></arg>
      <arg><option>apply</option></arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
  &gbp-pq helps one to manage quilt patches in Debian packages that are maintained
  with &git-buildpackage;. This is especially useful with packages using the
  3.0 (quilt) source format. With &gbp-pq; you can maintain the quilt patches
  that should be applied to a package on a separate branch called patch-queue
  branch. So if your Debian package lives on <replaceable>master</replaceable>
  the associated patch-queue branch will be called
  <replaceable>patch-queue/master</replaceable>.
    </para>
    <para>
   See <ulink url="https://honk.sigxcpu.org/piki/development/debian_packages_in_git/"></ulink> for example workflows.
    </para>
  </refsect1>
  <refsect1>
    <title>ACTIONS</title>
    <variablelist>
      <varlistentry>
        <term><option>import</option>
        </term>
        <listitem>
	  <para>
	Create a patch queue branch from quilt patches in debian/patches/ that
	are listed in debian/patches/series.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>export</option>
        </term>
        <listitem>
	  <para>
	Export the patches on the patch-queue branch associated to the current
	branch into a quilt patch series in debian/patches/ and update the
	series file.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>rebase</option>
        </term>
        <listitem>
	  <para>
	Switch to the patch-queue branch associated to the current branch and
	rebase it against the current branch.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>drop</option>
        </term>
        <listitem>
	  <para>
	Drop (delete) the patch queue associated to the current branch. So if
	you're on branch <replaceable>foo</replaceable> this would drop branch
	<replaceable>patch-queue/foo</replaceable>.
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>apply</option>
        </term>
        <listitem>
	  <para>
	Add a single patch to the patch-queue similar to using
	<command>git-am</command>. Use <option>--topic</option> if you want
	the patch to appear in a separate subdir when exporting the patch queue
	using <option>export</option>. This can be used to separate upstream
	pathes from debian specific patches.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>
    <variablelist>
      <varlistentry>
        <term><option>--verbose</option></term>
	<term><option>-v</option></term>
        <listitem>
          <para>verbose execution</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--color=</option><replaceable>[auto|on|off]</replaceable>
        </term>
        <listitem>
          <para>Whether to use colored output.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--[no-]patch-numbers</option>
        </term>
        <listitem>
          <para>Whether the patch files should start with a number or not.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--topic=</option><replaceable>topic</replaceable>
        </term>
        <listitem>
          <para>Topic to use when importing a single patch</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--time-machine=</option><replaceable>NUM</replaceable>
        </term>
        <listitem>
	  <para>When importing a patch queue fails, go back commit by
	  commit on the current branch to check if the patch-queue applies
	  there. Do this at most <replaceable>NUM</replaceable> times. This can
	  be useful if the patch-queue doesn't apply to the current branch HEAD
	  anymore, e.g.  after importing a new upstream version.
	  </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>TAGS</title>
    <para>
    When exporting patches from a patch-queue branch &gbp-pq; will look at the
    patch header for special tags it recognizes. All tags need to start at the
    first column and require at least one whitespace after the colon.
    </para>
    <variablelist>
      <varlistentry>
        <term><option>Gbp-Pq-Topic:</option> <replaceable>topic</replaceable></term>
        <listitem>
	  <para>Moves the patch into a subdir called
	  <replaceable>topic</replaceable> when running <screen>&gbp-pq;
	  export</screen>. This allows for some structure below
	  <filename>debian/patches</filename>. </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>git-buildpackage</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>dpkg-source</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>quilt</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>

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

  </refsect1>
</refentry>
