<refentry id="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;
      &man.common.options.synopsis;
      <arg><option>--[no-]patch-numbers</option></arg>
      <arg><option>--topic=</option><replaceable>topic</replaceable></arg>
      <arg><option>--time-machine=</option><replaceable>num</replaceable></arg>
      <arg><option>--[no-]drop</option></arg>
      <arg><option>--force</option></arg>
      <group choice="plain">
        <arg><option>drop</option></arg>
        <arg><option>export</option></arg>
        <arg><option>import</option></arg>
        <arg><option>rebase</option></arg>
        <arg><option>switch</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 &gbp;. 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. The patches must apply
          without fuzz.
          </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>
      <varlistentry>
        <term><option>switch</option>
        </term>
        <listitem>
          <para>
          Switch to the patch-queue branch if on the base branch and switch
          to base branch if on patch-queue branch.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>
    <variablelist>
      &man.common.options.description;

      <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>
      <varlistentry>
        <term><option>--[no-]drop</option></term>
        <listitem>
          <para>Whether to drop (delete) the patch queue branch after
          a succesful export</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--force</option></term>
        <listitem>
          <para>In case of import even import if the branch already
            exists</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]: Ignore</option>
        </term>
        <listitem>
          <para>
          Ignores the commit, no patch is generated out of it.
          </para>
        </listitem>
      </varlistentry>
      <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>
      <varlistentry>
        <term><option>Gbp-Pq-Topic:</option> <replaceable>topic</replaceable>
        </term>
        <listitem>
          <para>
          Deprecated: use <option>Gbp[-Pq]: Topic</option>
          <replaceable>topic</replaceable> instead.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <xref linkend="man.gbp.buildpackage">,
      <citerefentry>
        <refentrytitle>dpkg-source</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>quilt</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>,
      <xref linkend="man.gbp.conf">
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>
      &dhusername; &dhemail;
    </para>
  </refsect1>
</refentry>
