Add documentation for gbp-{pg,pull.clone}

10 files changed, 301 insertions, 1 deletions

diff --git a/debian/rules b/debian/rules
index 60da789..5c53056 100755
--- a/debian/rules
+++ b/debian/rules
@@ -18,7 +18,7 @@ EXAMPLE_SCRIPTS=gbp-cowbuilder-sid gbp-pbuilder gbp-posttag-push
 
 DEB_COMPRESS_EXCLUDE=$(EXAMPLE_SCRIPTS)
 
-MANPAGES=$(patsubst %,docs/%.1,$(COMMANDS))
+MANPAGES=$(patsubst %,docs/%.1,$(COMMANDS) gbp-pq)
 MANUAL=docs/manual-html
 PYCHECKS=$(patsubst %,%.py,$(COMMANDS))
 PYCHECK_LEVEL=Error
diff --git a/docs/common.ent b/docs/common.ent
index 3ff5716..ff27a64 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -8,6 +8,9 @@
   <!ENTITY git-import-dsc	"<command>git-import-dsc</command>">
   <!ENTITY git-import-dscs	"<command>git-import-dscs</command>">
   <!ENTITY git-dch		"<command>git-dch</command>">
+  <!ENTITY gbp-pull		"<command>gbp-pull</command>">
+  <!ENTITY gbp-clone		"<command>gbp-clone</command>">
+  <!ENTITY gbp-pq		"<command>gbp-pq</command>">
   <!ENTITY gitcmd		"<command>git</command>">
   <!ENTITY gitkcmd		"<command>gitk</command>">
   <!ENTITY pbuildercmd		"<command>pbuilder</command>">
diff --git a/docs/man.gbp-clone.sgml b/docs/man.gbp-clone.sgml
new file mode 100644
index 0000000..6fa6f56
--- /dev/null
+++ b/docs/man.gbp-clone.sgml
@@ -0,0 +1,11 @@
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+  <!ENTITY % COMMON SYSTEM "common.ent">
+  %COMMON;
+  <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+  %MANPAGES;
+]>
+
+<reference>
+<title>git-buildpackage Manual</title>
+&man.gbp.clone;
+</reference>
diff --git a/docs/man.gbp-pq.sgml b/docs/man.gbp-pq.sgml
new file mode 100644
index 0000000..093ce2f
--- /dev/null
+++ b/docs/man.gbp-pq.sgml
@@ -0,0 +1,11 @@
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+  <!ENTITY % COMMON SYSTEM "common.ent">
+  %COMMON;
+  <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+  %MANPAGES;
+]>
+
+<reference>
+<title>git-buildpackage Manual</title>
+&man.gbp.pq;
+</reference>
diff --git a/docs/man.gbp-pull.sgml b/docs/man.gbp-pull.sgml
new file mode 100644
index 0000000..b2dedbd
--- /dev/null
+++ b/docs/man.gbp-pull.sgml
@@ -0,0 +1,11 @@
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+  <!ENTITY % COMMON SYSTEM "common.ent">
+  %COMMON;
+  <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+  %MANPAGES;
+]>
+
+<reference>
+<title>git-buildpackage Manual</title>
+&man.gbp.pull;
+</reference>
diff --git a/docs/manpages/gbp-clone.sgml b/docs/manpages/gbp-clone.sgml
new file mode 100644
index 0000000..559da83
--- /dev/null
+++ b/docs/manpages/gbp-clone.sgml
@@ -0,0 +1,97 @@
+<refentry id="gbp.man.gbp.clone">
+  <refentryinfo>
+    <address>
+      &dhemail;
+    </address>
+    <author>
+      &dhfirstname;
+      &dhsurname;
+    </author>
+  </refentryinfo>
+  <refmeta>
+   <refentrytitle>gbp-clone</refentrytitle>
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>&gbp-clone;</refname>
+
+    <refpurpose>Clone a repository from remote</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      &gbp-clone;
+
+      <arg><option>--verbose</option></arg>
+      <arg><option>--[no-]pristine-tar</option></arg>
+      <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg><option>--upstream-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg choice="plain"><replaceable>remote_uri</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+    &gbp-clone; clones a remote repository and sets up tracking branches for
+    the <emphasis>debian</emphasis>, <emphasis>upstream</emphasis> and
+    <emphasis>pristine-tar</emphasis> branches. This way you can easily update
+    later using &gbp-pull;.
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+
+    <variablelist>
+      <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>.
+        </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>--verbose</option></term>
+	<term><option>-v</option></term>
+        <listitem>
+          <para>verbose execution</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--pristine-tar</option>
+        </term>
+        <listitem>
+          <para>generate pristine-tar delta file</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  <refsect1>
+      &man.git.config-files;
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>git-buildpackage</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>gbp-pull</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+
+    <para>&dhusername; &dhemail;</para>
+
+  </refsect1>
+</refentry>
diff --git a/docs/manpages/gbp-pq.sgml b/docs/manpages/gbp-pq.sgml
new file mode 100644
index 0000000..f1fcb20
--- /dev/null
+++ b/docs/manpages/gbp-pq.sgml
@@ -0,0 +1,47 @@
+<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 a patch-queue branch</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      &gbp-pq;
+      <arg><option>export</option>|<option>import</option>|<option>rebase</option>|<option>drop</option></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+   See <ulink url="https://honk.sigxcpu.org/piki/development/debian_packages_in_git/"></ulink> for documentation.
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>git-buildpackage</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+
+    <para>&dhusername; &dhemail;</para>
+
+  </refsect1>
+</refentry>
diff --git a/docs/manpages/gbp-pull.sgml b/docs/manpages/gbp-pull.sgml
new file mode 100644
index 0000000..de5ac8c
--- /dev/null
+++ b/docs/manpages/gbp-pull.sgml
@@ -0,0 +1,114 @@
+<refentry id="gbp.man.gbp.pull">
+  <refentryinfo>
+    <address>
+      &dhemail;
+    </address>
+    <author>
+      &dhfirstname;
+      &dhsurname;
+    </author>
+  </refentryinfo>
+  <refmeta>
+   <refentrytitle>gbp-pull</refentrytitle>
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>&gbp-pull;</refname>
+
+    <refpurpose>Safely update a repository from remote</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      &gbp-pull;
+
+      <arg><option>--verbose</option></arg>
+      <arg><option>--redo-pq</option></arg>
+      <arg><option>--force</option></arg>
+      <arg><option>--[no-]pristine-tar</option></arg>
+      <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
+      <arg><option>--upstream-branch=</option><replaceable>branch_name</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+    &gbp-pull; updates the <emphasis>debian</emphasis>,
+    <emphasis>upstream</emphasis> and <emphasis>pristine-tar</emphasis>
+    branches from a remote repository in one go. It checks if the update is safe (would
+    result in a <emphasis>fast-forward</emphasis> merge) and aborts otherwise.
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>--force</option></term>
+        <listitem>
+	  <para>force update even if this results in a non fast forward update</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--redo-pq</option></term>
+        <listitem>
+	  <para>also rebuild the corresponding patch-queue using &gbp-pq;</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>.
+        </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>--verbose</option></term>
+	<term><option>-v</option></term>
+        <listitem>
+          <para>verbose execution</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--pristine-tar</option>
+        </term>
+        <listitem>
+          <para>generate pristine-tar delta file</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  <refsect1>
+      &man.git.config-files;
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>git-buildpackage</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>gbp-clone</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>gbp-pq</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+
+    <para>&dhusername; &dhemail;</para>
+
+  </refsect1>
+</refentry>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 21c5bf0..62115cf 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -3,5 +3,8 @@
 <!ENTITY man.git.importdscs SYSTEM "git-import-dscs.sgml">
 <!ENTITY man.git.buildpackage SYSTEM "git-buildpackage.sgml">
 <!ENTITY man.git.dch SYSTEM "git-dch.sgml">
+<!ENTITY man.gbp.pull SYSTEM "gbp-pull.sgml">
+<!ENTITY man.gbp.clone SYSTEM "gbp-clone.sgml">
+<!ENTITY man.gbp.pq SYSTEM "gbp-pq.sgml">
 <!ENTITY man.git.config-files SYSTEM "man.conffiles.sgml">
 <!ENTITY man.seealso.common SYSTEM "man.seealso.sgml">
diff --git a/docs/manual.sgml b/docs/manual.sgml
index eb97753..7977691 100644
--- a/docs/manual.sgml
+++ b/docs/manual.sgml
@@ -32,6 +32,9 @@
     &man.git.importdscs;
     &man.git.importorig;
     &man.git.dch;
+    &man.gbp.clone;
+    &man.gbp.pull;
+    &man.gbp.pq;
   </appendix>
   <appendix id="gbp.copyleft">
     <title>Copyright</title>