Date: Thu, 17 Aug 2017 10:42:12 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50682 - in head: en_US.ISO8859-1/books/porters-handbook/makefiles share/xml Message-ID: <201708171042.v7HAgCuH069028@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201708171042.v7HAgCuH069028>