Stefan Hajnoczi <stefanha@xxxxxxxxxx> writes:
> v2:
> * Use obj->type instead of re-parsing name for delimiter
> (Followed Brandon's suggestion but named the variable 'delim' since that
> name is used in other places and 'del' is used for deletion.)
> * Add tests
> * Update Patch 1 commit description with a more relevant example
> * PATCH instead of RFC, now works with all documented git-rev-parse(1) syntax
>
> git-grep(1)'s output is not consistent with git-rev-parse(1) revision syntax.
While I was queuing this series (which I think should become a
single patch in the final version), I was trying to see how it
should be described in the release note (aka an entry in the
periodicall "What's cooking" report). Here is how I explained it.
You may want to borrow some parts of the description, especially the
part that talks about <tree-ish>:<path> being a way to name a blob,
when updating the commit log message.
"git grep", when fed a tree-ish as an input, shows each hit
prefixed with "<tree-ish>:<path>:<lineno>:". As <tree-ish> is
almost always either a commit or a tag that points at a commit,
the early part of the output "<tree-ish>:<path>" can be used as
the name of the blob and given to "git show".
When <tree-ish> is a tree given in the extended SHA-1 syntax
(e.g. "<commit>:", or "<commit>:<dir>"), however, this results
in a string that does not name a blob (e.g. "<commit>::<path>"
or "<commit>:<dir>:<path>"). "git grep" has been taught to be
a bit more intelligent about these cases and omit a colon (in
the former case) or use slash (in the latter case) to produce
"<commit>:<path>" and "<commit>:<dir>/<path>" that can be used
as the name of a blob.
As a release note entry is written in a style different from the
commit log message, you would need to adjust the voice of the last
sentence (i.e. "Teach 'git grep' to ..." to give an order to the
codebase), but otherwise the above would make an understandable
justification for the change suitable in a log message.