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

Joey Hess [off-list ref] writes:

Junio C Hamano wrote:

quoted

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

Ah, "being worked on" does clarify it well, I think:

+ Note that "%f" is the name of the path that is being worked on. 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, but only act as filters on the
+ content provided to them on standard input.

Looks much better than the original text.  Thanks.

Another reason why you do not want to say "tracked" is for "git add"
that adds a brand-new file that is not yet tracked.  Technically,
"trackable file" may work but we have to add "trackable" to the
glossary, but so far we did without having to, and I'm reluctant to
invent yet another word, so...