Possible documentation error for "git revisions"

Possible documentation error for "git revisions"

[Will Palmer]

The Documentation/revisions.txt page may have a couple of errors in
it, regarding "searching for commits by commit message"

it states:

':/<text>', e.g. ':/fix nasty bug'::
A colon, followed by a slash, followed by a text, names
a commit whose commit message matches the specified regular expression.
This name returns the youngest matching commit which is
reachable from any ref, including HEAD.
The regular expression can match any part of the
commit message. To match messages starting with a string, one can use
e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what
is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a
literal '!' character, followed by 'foo'. Any other sequence beginning with
':/!' is reserved for now.
Depending on the given text, the shell's word splitting rules might
require additional quoting.

However, I believe that the ":/<text>" syntax now *always* refers to a
file in the tree-object,
never a search-by-commit-message. (I wasn't previously aware of this
change, but I like it!)

Instead, the syntax "HEAD^{/<text>}" *does* appear to perform the
search described by the
documentation for ":/<text>". This includes the possibility of
matching HEAD itself. in my
own workflow, I've never noticed the distinction, but this does feel
like a possible error in code,
rather than documentation. That said, removing the ability for
"HEAD^{/text}" to match HEAD
would potentially leave rev-parse with no method for referring to "the
first match, even if that
match is HEAD itself", which I think would be bad to remove.
Personally, I always type
HEAD^{/text} (or HEAD^{/!-text}) when searching for something "before"
HEAD, but I do feel
that I would "expect" that to match HEAD as well, for what it's worth.

Though fixing this as a matter of documentation would be a very small
change, I don't have
time right now personally to make it (including necessary steps of
verification, tracing the
history of when the documentation became out-of-date, ensuring this is
a documentation, not
code, issue, etc). So I'm unfortunately probably going to "fire and
forget" this bug report.

Thanks to anyone who can complete this!

-- Will Palmer