Add tag command

by splitting out the code from buildpackage

This is shorter than running

     gbp buildpackage --git-tag-only

Closes: #797086

7 files changed, 238 insertions, 24 deletions

diff --git a/docs/Makefile b/docs/Makefile
index 6ad326a3..4fdbecee 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -15,6 +15,7 @@ MAN1S = \
         gbp-pristine-tar  \
         gbp-pull          \
         gbp-push          \
+        gbp-tag           \
         gbp-buildpackage-rpm \
         gbp-import-srpm   \
         gbp-pq-rpm        \
diff --git a/docs/common.ent b/docs/common.ent
index fd9f68cb..2e3d09b6 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -35,6 +35,7 @@
   <!ENTITY gbp-pull		"<command>gbp&nbsp;pull</command>">
   <!ENTITY gbp-push		"<command>gbp&nbsp;push</command>">
   <!ENTITY gbp-rpm-ch           "<command>gbp rpm-ch</command>">
+  <!ENTITY gbp-tag              "<command>gbp tag</command>">
   <!ENTITY gbp.conf		"<filename>gbp.conf</filename>">
   <!ENTITY git-pbuilder		"<command>git-pbuilder</command>">
   <!ENTITY git-qemubuilder	"<command>git-pbuilder</command>">
diff --git a/docs/man.gbp-tag.sgml b/docs/man.gbp-tag.sgml
new file mode 100644
index 00000000..e4c8dafd
--- /dev/null
+++ b/docs/man.gbp-tag.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.tag;
+</reference>
diff --git a/docs/manpages/gbp-tag.sgml b/docs/manpages/gbp-tag.sgml
new file mode 100644
index 00000000..48504e2a
--- /dev/null
+++ b/docs/manpages/gbp-tag.sgml
@@ -0,0 +1,197 @@
+<refentry id="man.gbp.tag">
+  <refentryinfo>
+    <address>
+      &dhemail;
+    </address>
+    <author>
+      &dhfirstname;
+      &dhsurname;
+    </author>
+  </refentryinfo>
+  <refmeta><refentrytitle>gbp-tag</refentrytitle>
+    &dhsection;
+  </refmeta>
+  <refnamediv>
+    <refname>gbp-tag</refname>
+    <refpurpose>Tag a &debian; packages in a &git; repository</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      &gbp-tag;
+
+      &man.common.options.synopsis;
+      <arg><option>--ignore-branch</option></arg>
+      <arg><option>--[no-]ignore-new</option></arg>
+      <arg><option>--[no-]sign-tags</option></arg>
+      <arg><option>--keyid=</option><replaceable>GPG-KEYID</replaceable></arg>
+      <arg><option>--debian-branch=</option><replaceable>BRANCH_NAME</replaceable></arg>
+      <arg><option>--debian-tag=</option><replaceable>tag-format</replaceable></arg>
+      <arg><option>--debian-tag-msg=</option><replaceable>tag-msg-format</replaceable></arg>
+      <arg><option>--posttag=</option><replaceable>COMMAND</replaceable></arg>
+      <arg><option>--retag</option></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+    <para>
+      &gbp-tag; tags the current head commit appropriately. It will in order:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          Verify that it is being executed from the Debian branch.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Verify that the repository doesn't contain any uncommitted source
+          changes.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+	  Create a git tag using the information from <filename>debian/changelog</filename>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          (Optionally) call a post tag hook.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+    <variablelist>
+      &man.common.options.description;
+      <varlistentry>
+        <term><option>--posttag=</option><replaceable>COMMAND</replaceable>
+        </term>
+        <listitem>
+          <para>
+            Execute <replaceable>COMMAND</replaceable> after creating the tag.
+          </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>--[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>--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>--debian-tag-msg=</option><replaceable>tag-msg-format</replaceable>
+        </term>
+        <listitem>
+          <para>Use this tag message format when signing &debian; versions,
+            default is <replaceable>%(pkg)s Debian release %(version)s</replaceable></para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--retag</option>
+        </term>
+        <listitem>
+          <para>
+            Don't fail tag operations if a tag with the same version
+            already exists. This is a command line only option that
+            cannot be specified via &gbp.conf;.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--debian-branch</option>=<replaceable>BRANCH_NAME</replaceable>
+        </term>
+        <listitem>
+          <para>
+            If you're not on this branch when invoking &gbp-tag; it will
+            fail. Default is <replaceable>master</replaceable>. This is done to
+            make sure you don't accidentally tag on the wrong branch.  Not
+            being on this branch will be ignored when using
+            <option>--ignore-branch</option>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--ignore-branch</option>
+        </term>
+        <listitem>
+          <para>
+            Don't check if the current branch matches
+            <replaceable>DEBIAN-BRANCH</replaceable>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--[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>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>EXAMPLES</title>
+    <para>
+      Create a tag with the current defaults
+    </para>
+    <screen>
+      &gbp-tag;
+    </screen>
+    <para>
+      Create using a more upstreamish tag format:
+    </para>
+    <screen>
+      &gbp-tag; --debian-tag='v%(version)s'
+    </screen>
+  </refsect1>
+  <refsect1>
+    &man.gbp.config-files;
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+    <para>
+      <xref linkend="man.gbp.buildpackage"/,
+      <xref linkend="man.gbp.push"/,
+      <xref linkend="man.gbp.conf"/,
+    </para>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+    <para>
+      &dhusername; &dhemail;
+    </para>
+  </refsect1>
+</refentry>
diff --git a/docs/manpages/gbp.sgml b/docs/manpages/gbp.sgml
index eff89f25..1a3c8e93 100644
--- a/docs/manpages/gbp.sgml
+++ b/docs/manpages/gbp.sgml
@@ -155,17 +155,18 @@
     <title>SEE ALSO</title>
     <para>
       <xref linkend="man.gbp.buildpackage"/,
+      <xref linkend="man.gbp.clone"/,
+      <xref linkend="man.gbp.create.remote.repo"/,
+      <xref linkend="man.gbp.dch"/,
+      <xref linkend="man.gbp.export.orig"/,
       <xref linkend="man.gbp.import.dsc"/,
       <xref linkend="man.gbp.import.dscs"/,
       <xref linkend="man.gbp.import.orig"/,
-      <xref linkend="man.gbp.dch"/,
       <xref linkend="man.gbp.pq"/,
       <xref linkend="man.gbp.pristine.tar"/,
-      <xref linkend="man.gbp.export.orig"/,
-      <xref linkend="man.gbp.create.remote.repo"/,
       <xref linkend="man.gbp.pull"/,
       <xref linkend="man.gbp.push"/,
-      <xref linkend="man.gbp.clone"/,
+      <xref linkend="man.gbp.tag"/,
       <citerefentry>
         <refentrytitle>git-pbuilder</refentrytitle>
         <manvolnum>1</manvolnum>
diff --git a/docs/manpages/manpages.ent b/docs/manpages/manpages.ent
index 9415946a..29289684 100644
--- a/docs/manpages/manpages.ent
+++ b/docs/manpages/manpages.ent
@@ -1,23 +1,25 @@
-<!ENTITY man.gbp.importorig SYSTEM "gbp-import-orig.sgml">
-<!ENTITY man.gbp.importdsc SYSTEM "gbp-import-dsc.sgml">
-<!ENTITY man.gbp.importdscs SYSTEM "gbp-import-dscs.sgml">
+<!ENTITY man.gbp SYSTEM "gbp.sgml">
 <!ENTITY man.gbp.buildpackage SYSTEM "gbp-buildpackage.sgml">
+<!ENTITY man.gbp.buildpackage.rpm SYSTEM "gbp-buildpackage-rpm.sgml">
+<!ENTITY man.gbp.clone SYSTEM "gbp-clone.sgml">
+<!ENTITY man.gbp.conf SYSTEM "gbp.conf.sgml">
 <!ENTITY man.gbp.config SYSTEM "gbp-config.sgml">
+<!ENTITY man.gbp.config-files SYSTEM "man.conffiles.sgml">
+<!ENTITY man.gbp.create.remote.repo SYSTEM "gbp-create-remote-repo.sgml">
 <!ENTITY man.gbp.dch SYSTEM "gbp-dch.sgml">
 <!ENTITY man.gbp.exportorig SYSTEM "gbp-export-orig.sgml">
-<!ENTITY man.gbp SYSTEM "gbp.sgml">
+<!ENTITY man.gbp.import.srpm SYSTEM "gbp-import-srpm.sgml">
+<!ENTITY man.gbp.importdsc SYSTEM "gbp-import-dsc.sgml">
+<!ENTITY man.gbp.importdscs SYSTEM "gbp-import-dscs.sgml">
+<!ENTITY man.gbp.importorig SYSTEM "gbp-import-orig.sgml">
+<!ENTITY man.gbp.pq SYSTEM "gbp-pq.sgml">
+<!ENTITY man.gbp.pq.rpm SYSTEM "gbp-pq-rpm.sgml">
 <!ENTITY man.gbp.pristine.tar SYSTEM "gbp-pristine-tar.sgml">
 <!ENTITY man.gbp.pull SYSTEM "gbp-pull.sgml">
 <!ENTITY man.gbp.push SYSTEM "gbp-push.sgml">
-<!ENTITY man.gbp.clone SYSTEM "gbp-clone.sgml">
-<!ENTITY man.gbp.pq SYSTEM "gbp-pq.sgml">
-<!ENTITY man.gbp.create.remote.repo SYSTEM "gbp-create-remote-repo.sgml">
-<!ENTITY man.gbp.conf SYSTEM "gbp.conf.sgml">
-<!ENTITY man.gbp.config-files SYSTEM "man.conffiles.sgml">
-<!ENTITY man.seealso.common SYSTEM "man.seealso.sgml">
-<!ENTITY man.gbp.buildpackage.rpm SYSTEM "gbp-buildpackage-rpm.sgml">
-<!ENTITY man.gbp.import.srpm SYSTEM "gbp-import-srpm.sgml">
-<!ENTITY man.gbp.pq.rpm SYSTEM "gbp-pq-rpm.sgml">
 <!ENTITY man.gbp.rpm.ch SYSTEM "gbp-rpm-ch.sgml">
+<!ENTITY man.gbp.tag SYSTEM "gbp-tag.sgml">
+<!ENTITY man.seealso.common SYSTEM "man.seealso.sgml">
+
 <!ENTITY % COMMON.OPTIONS SYSTEM "man.common-options.ent">
 %COMMON.OPTIONS;
diff --git a/docs/manual.sgml b/docs/manual.sgml
index 35809ada..234e55dc 100644
--- a/docs/manual.sgml
+++ b/docs/manual.sgml
@@ -30,18 +30,19 @@
     <title>Command Reference</title>
     &man.gbp;
     &man.gbp.buildpackage;
+    &man.gbp.clone;
+    &man.gbp.config;
+    &man.gbp.create.remote.repo;
+    &man.gbp.dch;
+    &man.gbp.exportorig;
     &man.gbp.importdsc;
     &man.gbp.importdscs;
     &man.gbp.importorig;
-    &man.gbp.dch;
-    &man.gbp.clone;
-    &man.gbp.config;
+    &man.gbp.pq;
+    &man.gbp.pristine.tar;
     &man.gbp.pull;
     &man.gbp.push;
-    &man.gbp.pristine.tar;
-    &man.gbp.exportorig;
-    &man.gbp.pq;
-    &man.gbp.create.remote.repo;
+    &man.gbp.tag;
     &man.gbp.conf;
   </appendix>
   <appendix id="gbp.copyleft">