Re: [PATCH] revisions.txt: mention <rev>~ form

From: Denton Liu <liu.denton@gmail.com>
Date: Apr 22, 2019, 07:39 UTC
Message-ID: <20190422073935.GA7660@archbookpro.localdomain>
In-Reply-To: <xmqqv9z67doq.fsf@gitster-ct.c.googlers.com>

On Mon, Apr 22, 2019 at 03:32:21PM +0900, Junio C Hamano wrote:

Show 11 quoted lines

> Denton Liu <liu.denton@gmail.com> writes:
> 
> > @@ -139,7 +139,9 @@ thing no matter the case.
> >    '<rev>{caret}0' means the commit itself and is used when '<rev>' is the
> >    object name of a tag object that refers to a commit object.
> >  
> > -'<rev>{tilde}<n>', e.g. 'master{tilde}3'::
> > +'<rev>{tilde}[<n>]', e.g. 'HEAD~, master{tilde}3'::
> 
> Why doesn't this example say "HEAD{tilde}, master{tilde}3" instead,
> I wonder?

According to the doc-diff, it doesn't really make a difference:

	diff --git a/14c0f8d3ab6c36672189cd2dd217f4617d12ccba/home/denton/share/man/man7/gitrevisions.7 b/18c8ed70602271a28c93df922eb3da8fb7563e2e/home/denton/share/man/man7/gitrevisions.7
	index 6f0dc7b8fb..ef23d49e00 100644
	--- a/14c0f8d3ab6c36672189cd2dd217f4617d12ccba/home/denton/share/man/man7/gitrevisions.7
	+++ b/18c8ed70602271a28c93df922eb3da8fb7563e2e/home/denton/share/man/man7/gitrevisions.7
	@@ -146,19 +146,20 @@ SPECIFYING REVISIONS
				This suffix is also accepted when spelled in uppercase, and means
				the same thing no matter the case.
	 
	-       <rev>^, e.g. HEAD^, v1.5.1^0
	+       <rev>^[<n>], e.g. HEAD^, v1.5.1^0
				A suffix ^ to a revision parameter means the first parent of that
				commit object.  ^<n> means the <n>th parent (i.e.  <rev>^ is
				equivalent to <rev>^1). As a special rule, <rev>^0 means the commit
				itself and is used when <rev> is the object name of a tag object
				that refers to a commit object.
	 
	-       <rev>~<n>, e.g. master~3
	-           A suffix ~<n> to a revision parameter means the commit object that
	-           is the <n>th generation ancestor of the named commit object,
	-           following only the first parents. I.e.  <rev>~3 is equivalent to
	-           <rev>^^^ which is equivalent to <rev>^1^1^1. See below for an
	-           illustration of the usage of this form.
	+       <rev>~[<n>], e.g. HEAD~, master~3
	+           A suffix ~ to a revision parameter means the first parent of that
	+           commit object. A suffix ~<n> to a revision parameter means the
	+           commit object that is the <n>th generation ancestor of the named
	+           commit object, following only the first parents. I.e.  <rev>~3 is
	+           equivalent to <rev>^^^ which is equivalent to <rev>^1^1^1. See
	+           below for an illustration of the usage of this form.
	 
			<rev>^{<type>}, e.g. v0.99.8^{commit}
				A suffix ^ followed by an object type name enclosed in brace pair

That being said, this is a typo on my part and it should really say {tilde}.

Show 6 quoted lines

> 
> > +  A suffix '{tilde}' to a revision parameter means the first parent of
> > +  that commit object.
> >    A suffix '{tilde}<n>' to a revision parameter means the commit
> >    object that is the <n>th generation ancestor of the named
> >    commit object, following only the first parents.  I.e. '<rev>{tilde}3' is