Re: [PATCH v2 0/2] grep: make output consistent with revision syntax

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 20, 2017, 23:11 UTC
Message-ID: <xmqq1svxwclj.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170120171126.16269-1-stefanha@redhat.com>

Stefan Hajnoczi <stefanha@redhat.com> writes:

Show 9 quoted lines

> 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.