docs: Move to xml

Closes: #877322

1 files changed, 400 insertions, 0 deletions

diff --git a/docs/manpages/gbp-import-orig.xml b/docs/manpages/gbp-import-orig.xml
new file mode 100644
index 00000000..ed4ce43f
--- /dev/null
+++ b/docs/manpages/gbp-import-orig.xml
@@ -0,0 +1,400 @@
+<refentry id="man.gbp.import.orig">
+  <refentryinfo>
+    <address>
+      &dhemail;
+    </address>
+    <author>
+      &dhfirstname;
+      &dhsurname;
+    </author>
+  </refentryinfo>
+  <refmeta>
+    <refentrytitle>gbp-import-orig</refentrytitle>
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>gbp-import-orig</refname>
+    <refpurpose>Import an upstream source into a git repository</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      &gbp-import-orig;
+
+      &man.common.options.synopsis;
+      <arg><option>--upstream-version=</option><replaceable>version</replaceable></arg>
+      <arg><option>--[no-]merge</option></arg>
+      <arg><option>--merge-mode=</option><replaceable>[auto|merge|replace]</replaceable></arg>
+      <arg><option>--upstream-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg><option>--upstream-vcs-tag=</option><replaceable>tag-format</replaceable></arg>
+      <arg><option>--[no-]sign-tags</option></arg>
+      <arg><option>--keyid=</option><replaceable>gpg-keyid</replaceable></arg>
+      <arg><option>--upstream-tag=</option><replaceable>tag-format</replaceable></arg>
+      <arg rep='repeat'><option>--filter=</option><replaceable>pattern</replaceable></arg>
+      <arg rep='repeat'><option>--component=</option><replaceable>component</replaceable></arg>
+      <arg><option>--[no-]pristine-tar</option></arg>
+      <arg><option>--[no-]filter-pristine-tar</option></arg>
+      <arg><option>--[no-]symlink-orig</option></arg>
+      <arg><option>--postimport=cmd</option></arg>
+      <arg><option>--[no-]interactive</option></arg>
+      <arg><option>--[no-]rollback</option></arg>
+      <group choice="plain">
+        <arg choice="plain"><replaceable>filename</replaceable></arg>
+        <arg choice="plain"><replaceable>url</replaceable></arg>
+        <arg><option>--uscan</option></arg>
+      </group>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+      &gbp-import-orig; imports upstream sources into a &git;
+      repository. It can import from three sources:
+    </para>
+    <orderedlist>
+      <listitem>
+	<para>
+	  <replaceable>filename</replaceable>: A file in the local
+	  file system. Gzip, bzip2, lzma and xz compressed tar
+	  archives, zip archives and already unpacked source trees are
+	  supported.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <replaceable>url</replaceable>: The tarball is downloaded
+	  from a <replaceable>http</replaceable>
+	  or <replaceable>https</replaceable> <replaceable>url</replaceable>.
+	  This needs the python-request package installed.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <option>--uscan</option>: The latest upstream version is fetched
+	  via &uscan; relying on <filename>debian/watch</filename>.
+	</para>
+      </listitem>
+    </orderedlist>
+    <para>
+      If the tarballs name is already of the form
+      <replaceable>package-name_version.orig.tar.gz</replaceable>, the
+      version information is determined from the tarball's filename,
+      otherwise it can be given on the command line
+      via <option>--upstream-version</option>.  If the source package
+      name or version can't be determined, &gbp-import-orig; will
+      prompt for it unless <option>--no-interactive</option> is given.
+    </para>
+    <para>
+      The sources are placed on the upstream branch (default:
+      <replaceable>upstream</replaceable>), tagged and merged onto the
+      debian branch (default: <replaceable>master</replaceable>).  This
+      is either done using plain <command>git merge</command>
+      or by creating a new tree that consists of the new
+      upstream version plus the <filename>debian/</filename>
+      directory. The later is used for source format 3.0
+      (quilt) packages since direct modifications of the upstream
+      sources are not allowed in that format and so a 1:1 replacement
+      of the upstream sources is almost always desired. It can
+      be tweaked via the <option>--merge-mode</option>.
+    </para>
+    <para>In case of an error &gbp-import-orig; will rollback (undo)
+      all changes it has done to the repository (see
+      the <option>--rollback</option> option).
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+    <variablelist>
+      &man.common.options.description;
+
+      <varlistentry>
+        <term><option>--upstream-version</option>=<replaceable>version</replaceable></term>
+        <term><option>-u</option><replaceable>version</replaceable></term>
+        <listitem>
+          <para>
+          The upstream version number
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[no-]merge</option></term>
+        <listitem>
+          <para>
+          Merge the upstream branch to the &debian; branch after import
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--merge-mode=</option><replaceable>[auto|merge|replace]</replaceable></term>
+        <listitem>
+          <para>
+            How to fold the newly imported upstream source to the
+            &debian; packaging branch after import.
+	  </para>
+	  <para>
+	    <replaceable>merge</replaceable> does a
+	    &git; <command>merge</command> leaving you on your own in
+	    case of merge conflict resolution.
+	  </para>
+	  <para>
+	    <replaceable>replace</replaceable> mode on the
+	    other hand makes the head of the &debian; packaging branch
+	    identical to the newly imported tree but preserves the
+	    content of the <filename>debian/</filename> directory
+	    while keeping the current head as well as the newly
+	    important trees as parents of the generated commit. This is
+	    similar to a <option>theirs</option> merge strategy while
+	    preserving <filename>debian/</filename>.
+          </para>
+	  <para>
+	    The default is <replaceable>auto</replaceable> which
+	    uses <replaceable>replace</replaceable> for 3.0 (quilt) packages
+	    and <replaceable>merge</replaceable> otherwise.
+	  </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--upstream-branch</option>=<replaceable>branch_name</replaceable>
+        </term>
+        <listitem>
+          <para>
+          The branch in the &git; repository the upstream sources are put
+          onto. Default is <replaceable>upstream</replaceable>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--debian-branch</option>=<replaceable>branch_name</replaceable>
+        </term>
+        <listitem>
+          <para>
+          The branch in the &git; repository the &debian; package is being
+          developed on, default is <replaceable>master</replaceable>. After
+          importing the new sources on the upstream branch, &gbp-import-orig;
+          will try to merge the new version onto this branch.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--upstream-vcs-tag</option>=<replaceable>tag-format</replaceable>
+        </term>
+        <listitem>
+          <para>
+          Add <replaceable>tag-format</replaceable> as additional parent to the
+          commit of the upstream tarball. Useful when upstream uses git and you
+          want to link to its revision history. The
+          <replaceable>tag-format</replaceable> can be a pattern similar to
+          what <option>--upstream-tag</option> supports.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[no-]sign-tags</option>
+        </term>
+        <listitem>
+          <para>
+          GPG sign all created tags
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--keyid=</option><replaceable>gpg-keyid</replaceable>
+        </term>
+        <listitem>
+          <para>
+          use this keyid for gpg signing tags
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--upstream-tag=</option><replaceable>tag-format</replaceable>
+        </term>
+        <listitem>
+          <para>
+          use this tag format when tagging upstream versions,
+          default is <replaceable>upstream/%(version)s</replaceable>
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--import-msg=</option><replaceable>msg-format</replaceable>
+        </term>
+        <listitem>
+          <para>
+          use this format string for the commit message when importing upstream
+          versions, default is
+          <replaceable>New upstream version %(version)s</replaceable>
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--filter=</option><replaceable>pattern</replaceable>
+        </term>
+        <listitem>
+          <para>
+          filter out files glob-matching pattern. Can be given multiple times.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--component=</option><replaceable>COMPONENT</replaceable>
+        </term>
+        <listitem>
+          <para>
+	    When importing the upstream tarball also look for an additional tarball
+	    with component name <replaceable>COMPONENT</replaceable>. E.g. in
+	    <filename>hello-debhelper_1.0.orig-foo.tar.gz</filename>
+	    the component would be <replaceable>foo</replaceable>. The additional
+	    tarball is expected to be in the same directory than the upstream tarball
+	    and to use the same compression type.
+	  </para>
+	  <para>
+	    Using additional original tarballs is a feature of the 3.0
+	    (quilt) source format. See
+	    the <command>dpkg-source</command> manpage for
+	    details. This is currently considered an experimental
+	    feature and might change incompatibly.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[no-]pristine-tar</option>
+        </term>
+        <listitem>
+          <para>
+          generate <command>pristine-tar</command> delta file
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[no-]filter-pristine-tar</option>
+        </term>
+        <listitem>
+          <para>
+          if using a filter, also filter the files out of the tarball
+          passed to <command>pristine-tar</command>
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[no-]symlink-orig</option></term>
+        <listitem>
+          <para>
+          Whether to create and keep a symlink from the upstream tarball
+          to a &debian; policy conformant upstream tarball name located in
+          <filename class="directory">../</filename>.
+          </para>
+          <para>
+          This is a good idea if not using <command>pristine-tar</command>
+          since it avoids creating a new tarball with a different md5sum.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--postimport=<replaceable>cmd</replaceable></option></term>
+        <listitem>
+          <para>
+          Run <replaceable>cmd</replaceable> after the import. The
+          hook gets the following environment variables passed:
+	  <variablelist>
+	    <varlistentry>
+	      <term><envar>GBP_BRANCH</envar></term>
+	      <listitem><para>
+		  The name of the Debian packaging branch
+	      </para></listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><envar>GBP_TAG</envar></term>
+	      <listitem><para>
+		  The name of the just created upstream tag
+	      </para></listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><envar>GBP_UPSTREAM_VERSION</envar></term>
+	      <listitem><para>
+		  The just imported upstream version
+	      </para></listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><envar>GBP_DEBIAN_VERSION</envar></term>
+	      <listitem><para>
+		  The Debian version of the package with a Debian
+		  revision of '-1'
+	      </para></listitem>
+	    </varlistentry>
+	  </variablelist>
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--uscan</option></term>
+        <listitem>
+          <para>
+          Use &uscan; to fetch new upstream version.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[no-]interactive</option></term>
+        <listitem>
+          <para>
+          Run command interactively, i.e. ask package name and version if
+          needed.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[no-]rollback</option></term>
+        <listitem>
+          <para>
+	    Rollback changes in case of an error.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>EXAMPLES</title>
+    <para>
+    Download and import a new upstream version using the information from <filename>debian/watch</filename>
+    </para>
+    <screen>
+      &gbp-import-orig; --uscan</screen>
+    <para>
+      Fetch tarball from an URL
+    </para>
+    <screen>
+      &gbp-import-orig; https://debian.example.com/sid/upstream-tarball-0.1.tar.gz</screen>
+    <para>
+    Import a local tarball
+    </para>
+    <screen>
+      &gbp-import-orig; ../upstream-tarball-0.1.tar.gz</screen>
+  </refsect1>
+  <refsect1>
+    &man.gbp.config-files;
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+    <para>
+      <xref linkend="man.gbp.buildpackage"/,
+      <xref linkend="man.gbp.import.dsc"/,
+      <xref linkend="man.gbp.import.dscs"/,
+      <xref linkend="man.gbp.dch"/,
+      <xref linkend="man.gbp.conf"/,
+      <citerefentry>
+        <refentrytitle>uscan</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      &man.seealso.common;
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+    <para>
+    &dhusername; &dhemail;
+    </para>
+  </refsect1>
+</refentry>
+<!--  LocalWords:  xz lzma bzip gzip tarball
+ -->