Re: [PATCH 2/4] add smudge-to-file and clean-from-file filter configuration

From: Joey Hess <id@joeyh.name>
Date: Jun 17, 2016, 13:13 UTC
Message-ID: <20160617131311.GC24025@kitenet.net>
In-Reply-To: <xmqqy4643ig1.fsf@gitster.mtv.corp.google.com>

Junio C Hamano wrote:

> There is what we would want to fix, though.  "worktree file" should
> be spelled "working tree file". This used not to matter before "git
> worktree" was invented (before that we used these two terms
> interchangeably), but these days the distinction matters.

The existing documentation that I am patching uses the term "worktree file" which is why I continued to use that wording.

(Unless this is a documentation transition that you want to happen peicemeal as documentation is updated for other reasons?)

Show 5 quoted lines

> > +filter.<driver>.clean-from-file::
> 
> Documentation/config.txt hopefully lists all the configuration, but
> I do not see anything that uses 'words-joined-with-dash' format.
> Please do not invent new out-of-convention names.

Point taken; I'll use cleanFromFile and smudgeToFile.

Here's a revised version of the documentation that I think takes the other suggestions onboard. I emphasise that clean and smudge operate as filters, to contrast better with cleanFromFile and smudgeToFile not operating as regular stdio filters.

 filter.<driver>.clean::
-       The command which is used to convert the content of a worktree
+       The command which is used as a filter to convert the content of a worktree
        file to a blob upon checkin.  See linkgit:gitattributes[5] for
        details.
 
 filter.<driver>.smudge::
-       The command which is used to convert the content of a blob
+       The command which is used as a filter to convert the content of a blob
        object to a worktree file upon checkout.  See
        linkgit:gitattributes[5] for details.
 
+filter.<driver>.cleanFromFile::
+       Similar to filter.<driver>.clean but the specified command 
+       directly accesses a worktree file on disk, rather than
+       receiving the file content from standard input. 
+       In the command, "%p" is replaced with the name of the file. 
+       Only used when filter.<driver>.clean is also configured.
+       See linkgit:gitattributes[5] for details.
+
+filter.<driver>.smudgeToFile::
+       Similar to filter.<driver>.smudge but the specified command
+       writes the content of a blob directly to a worktree file,
+       rather than to standard output.
+       In the command, "%p" is replaced with the name of the file.
+       Only used when filter.<driver>.smudge is also configured.
+       See linkgit:gitattributes[5] for details.
+

This could be extended more, but I think this should describe the config settings concisely and point to the more involved discussion of filter drivers in gitattributes.

-- 
see shy jo