os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a USE_GITHUB example on how to use git describe.

Browse source 
Reviewed by:	bcr
Sponsored by:	Absolight
Differential Revision:	https://reviews.freebsd.org/D12047
This commit is contained in:
Mathieu Arnold 2017-08-17 10:42:12 +00:00
parent 12f81ec349
commit a25cc9cf12
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=50682
2 changed files with 81 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

80
en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
View file

@ -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>
&lt;
&prompt.user; <userinput>pkg version -t 0.7.3.14 0.7.4</userinput>
&lt;</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>

1
share/xml/man-refs.ent
View file

@ -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>">