svn commit: r50682 - in head: en_US.ISO8859-1/books/porters-handbook/makefiles share/xml

[Mathieu Arnold]

Author: mat
Date: Thu Aug 17 10:42:12 2017
New Revision: 50682
URL: https://svnweb.freebsd.org/changeset/doc/50682

Log:
  Add a USE_GITHUB example on how to use git describe.
  
  Reviewed by:	bcr
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D12047

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
  head/share/xml/man-refs.ent

Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Thu Aug 17 08:07:42 2017	(r50681)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Thu Aug 17 10:42:12 2017	(r50682)
@@ -2549,6 +2549,86 @@ GH_TAGNAME=	c472d66b</programlisting>
 	  future.</para>
       </example>
 
+      <example xml:id="makefile-master_sites-github-ex5">
+	<title>Using <varname>USE_GITHUB</varname> to Access
+	  a Commit Between Two Versions</title>
+
+	<para>If the current version of the software uses a
+	  <application>Git</application> tag, and the port needs to be
+	  updated to a newer, intermediate version, without a tag, use
+	  &man.git-describe.1; to find out the version to use:</para>
+
+	<screen>&prompt.user; <userinput>git describe --tags <replaceable>f0038b1</replaceable></userinput>
+v0.7.3-14-gf0038b1</screen>
+
+	<para><literal>v0.7.3-14-gf0038b1</literal> can be split into
+	  three parts:</para>
+
+	<variablelist>
+	  <varlistentry>
+	    <term><literal>v0.7.3</literal></term>
+
+	    <listitem>
+	      <para>This is the last <application>Git</application>
+		tag that appears in the commit history before the
+		requested commit.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>-14</literal></term>
+
+	    <listitem>
+	      <para>This means that the requested commit,
+		<literal>f0038b1</literal>, is the 14th commit after
+		the <literal>v0.7.3</literal> tag.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>-gf0038b1</literal></term>
+
+	    <listitem>
+	      <para>The <literal>-g</literal> means
+		<quote><application>Git</application></quote>, and
+		the <literal>f0038b1</literal> is the commit hash
+		that this reference points to.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+
+	<programlisting>PORTNAME=	bar
+DISTVERSIONPREFIX=  v
+DISTVERSION=	0.7.3-14
+DISTVERSIONSUFFIX=  -gf0038b1
+
+USE_GITHUB=	yes</programlisting>
+
+	<para>This creates a versioning scheme that increases over
+	  time (well, over commits), and does not conflict with the
+	  creation of a <literal>0.7.4</literal> version.
+	  (See <xref linkend="makefile-versions-ex-pkg-version"/> for
+	  details on &man.pkg-version.8;):</para>
+
+	<screen>&prompt.user; <userinput>pkg version -t 0.7.3 0.7.3.14</userinput>
+<
+&prompt.user; <userinput>pkg version -t 0.7.3.14 0.7.4</userinput>
+<</screen>
+
+	<note>
+	  <para>If the requested commit is the same as a tag, a
+	    shorter description is shown by default.  The longer
+	    version is equivalent:</para>
+
+	  <screen>&prompt.user; <userinput>git describe --tags <replaceable>c66c71d</replaceable></userinput>
+v0.7.3
+&prompt.user; <userinput>git describe --tags --long <replaceable>c66c71d</replaceable></userinput>
+v0.7.3-0-gc66c71d</screen>
+
+	</note>
+
+      </example>
+
       <sect3 xml:id="makefile-master_sites-github-multiple">
 	<title>Fetching Multiple Files from GitHub</title>
 

Modified: head/share/xml/man-refs.ent
==============================================================================
--- head/share/xml/man-refs.ent	Thu Aug 17 08:07:42 2017	(r50681)
+++ head/share/xml/man-refs.ent	Thu Aug 17 10:42:12 2017	(r50682)
@@ -270,6 +270,7 @@
 <!ENTITY man.getfacl.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.getopt.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>getopt</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.getopts.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>getopts</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
+<!ENTITY man.git-describe.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>git-describe</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.git-submodule.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>git-submodule</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.glob.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>glob</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.gnu-ar.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>gnu-ar</refentrytitle><manvolnum>1</manvolnum></citerefentry>">