Subject: Re: [PATCH] object-name: fix reversed ordering with magic pathspecs

From: Junio C Hamano <[email-masked]>
Date: Fri, 06 Dec 2024 20:57:04 +0900

"Kristoffer Haugsbakk" <[email-masked]> writes:

> On Fri, Dec 6, 2024, at 10:51, Patrick Steinhardt wrote:
>> It was reported
>
> It would be nice with a hyperlink since this email is not part of the
> email thread for the report.
>
> https://lore.kernel.org/git/[email-masked]/T/#mae906ec74d5657e702165e29b90927f730280c29
>
>> It was reported that magic pathspecs started to return results in
>
> I’m not used to this being called “magic pathspecs” as a user.
> gitglossary(7) talks about (magic) pathspecs as filepaths.

Thanks for catching the mistaken phrasing.  It would have caused
unnecessary confusion later to "git log" readers.

The syntax to say that the following path is from the top-level of
the working tree even when you are running the command from a
subdirectory, e.g.

    cd Documentation
    git log :/t

is described in gitglossary(7):

    A pathspec that begins with a colon `:` has special meaning.  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 "magic signature" consists of ASCII symbols that are neither
    alphanumeric, glob, regex special characters nor colon.
    The optional colon that terminates the "magic signature" can be
    omitted if the pattern begins with a character that does not belong to
    "magic signature" symbol set and is not a colon.

and even though the word "magic" signature is used, there is no
definition given for the entire construct, i.e. the pathspec that
uses a special meaning introduced by the use of "colon followed by
one or more magic signature letters".  We probably should add a
sentence to officially define it, if only to reduce the need for
exchanges like this ;-)

    ... and is not a colon.  Such a pathspec that uses these "magic"
    meaning is called "magic pathspec".

But more importantly, the syntax that triggered this topic in

<CAKOEJdcPYn3O01p29rVa+xv=[email-masked]>

is *NOT* a magic pathspec at all.  It is a revision syntax to name
the first commit that is reachable from the current HEAD with a
commit log message, that matches the given patterh, i.e.

    git show ":/my message"

which is a (rather lousy) short-hand for a more general

    git show "HEAD^{/my message}"

i.e. <startingRev>^{/<pattern>}.  There is no specific name for
this syntax.

I suspect that "filepath" you mentioned may be something some folks
(but not me or any other long timers) would call yet another syntax,
which is :<path>, that names the object sitting at <path> in the
index.  Because ":/myMessage" look so similar to ":myFile", yet
they mean so different things, as I said, ":/myMessage" is a rather
lousy short-hand for the more general "^{/<pattern>}" suffix that
is less ambiguous.

Patrick, let's not use a wrong word.  This is not about pathspec at
all, and is a revision syntax.  As there is no specific jargon for
the syntax, here is what I would write, if I were explaining the
problem being solved:

    Recently it was reported [*1*] that "look for the youngest
    reachable commit with log message that match the given pattern"
    syntax (e.g. :/myMessagePattern, or HEAD^{/myMessagePattern})
    started to show older commit.

    [Footnote]
    *1* <CAKOEJdcPYn3O01p29rVa+xv=[email-masked]>

Thanks.