Re: [PATCH 1/4] clarify %f documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 17, 2016, 03:25 UTC
Message-ID: <xmqqfusc33aa.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160617024803.GB17088@kitenet.net>

Joey Hess <id@joeyh.name> writes:

Show 16 quoted lines

> Junio C Hamano wrote:
>> I agree that "the name of the file" can be interpreted in many ways,
>> and I agree that it would be a good idea to find a better phrase to
>> name the path that is being worked on, but I do not think "the file
>> in the git repository" is that phrase.
>
>> I think using the word "path" somewhere in the updated description
>> is more likely to have the effect you desire.
>
> "path" is also very ambiguous. I see that "tracked" is often used to
> describe what %f is, so how about:
>  
> + Note that "%f" is the name of a file tracked by Git. Depending on the
> + version that is being filtered, the corresponding file on disk may not
> + exist, or may have different contents. So, smudge and clean commands should
> + not try to access the file on disk.

I think that places stress on a wrong point.

I do have a preference between "file" or "path", merely because, as I showed already (go back and read what you are responding to), the preceding paragraphs all talk in terms of "paths". But that is not the important part.

"tracked by Git" is not all that interesting, compared to the fact that your filter needs to give contents relevant to that path because that is what the command line argument Git gives you with '%f' means. It is not a random filename "tracked by Git". Among 47 other files tracked by Git, the single one being given is the one the code that drives the filter is WORKING ON, and I think that needs to be written in the description, hence "the path that is being worked on" was my suggestion.