Subject: Re: [PATCH 1/2] glossary-content.txt: remove an obsolete paragrah

From: Junio C Hamano <[email-masked]>
Date: Thu, 21 Nov 2013 10:13:48 -0800

Nguyễn Thái Ngọc Duy  <[email-masked]> writes:

> With the introduction of :(literal), :(glob) and :(icase), :(top) is
> no longer the only recognized magic signature.

You need to re-read the message you took hints that led to this
patch from (or, rather, the existing document around the area you
are patching, which led to the wording in that message from me).

The above is a list of magic words, but until you add the magic
signature ":!not_in_this_directory" for the ":(exclude)" magic word,
":/" still is the only magic signature.

Another moderately related tangent is this phrase in the existing
document:

    In the short form, the leading colon `:` is followed by zero or
    more "magic signature" letters (which optionally is terminated
    by another colon `:`), and the remainder is the pattern to match
    against the path. The optional colon that terminates the "magic
    signature" can be omitted if the pattern begins with a character
    that cannot be a "magic signature" and is not a colon.

While it is technically correct, the phrase "a character that cannot
be" is somewhat misleading, and I think it needs to be clarified by
rephrasing.

As we can see in a later paragaph:

    The "magic signature" consists of an ASCII symbol that is not
    alphanumeric. Currently only the slash `/` is recognized as a
    "magic signature"...

the correct way to read that "a character that cannot be a magic
signature" is "a character that is not 'an ASCII symbol that is not
alphanumeric'", which means you can do:

	:!/foo	- with magic signatures ! and /, pattern begins at 'f'

	:/#abc  - with magic signatures # and /, pattern begins at 'a',
	          even if in a particular version of Git, '#' magic
		  signature may be invalid and produce an error

	:/:#abc - with magic signature /, pattern is "#abc".

but because the definition of "magic signature" syntax comes later
than "cannot be", it is prone to be misinterpreted as "anything that
is not currently defined as a magic signature (namely, '/')".

> Signed-off-by: Nguyễn Thái Ngọc Duy <[email-masked]>
> ---
>  .. on top of nd/magic-pathspec..
>
>  Documentation/glossary-content.txt | 4 ----
>  1 file changed, 4 deletions(-)
>
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index e470661..e22b524 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -379,10 +379,6 @@ full pathname may have special meaning:
>  Glob magic is incompatible with literal magic.
>  --
>  +
> -Currently only the slash `/` is recognized as the "magic signature",
> -but it is envisioned that we will support more types of magic in later
> -versions of Git.
> -+
>  A pathspec with only a colon means "there is no pathspec". This form
>  should not be combined with other pathspec.