The Filter API contains singleton Entry-points which are agnostic to `FilterMode`, does having `Clean` and `Smudge` entry-points make sense?

[whoisj]

Today the Filter object (the API we expose to lib consumers) contains the following entry-points:

• virtual void Initialize()
• virtual void Complete(string path, string root, Stream output)
• virtual void Create(string path, string root, FilterMode)
• virtual void Clean(string path, string root, Stream input, Stream output)
• virtual void Smudge(string path, string root, Stream input, Stream output)

This is very uneven and, to my OCD, a fairly inconsistent API. I'm responsible and I'd like to change it, however some have already taken a dependency. In the spirit of #1103 I suggest changing the API to the following.

• virtual void Initialize()
• virtual void Complete(string root, string path, Stream output, FilterMode mode)
• virtual void Create(string root, string path, FilterMode mode)
• virtual void Apply(string root, string path, Stream input, Stream output, FilterMode mode)

I believe this is a simplified API which presents a consistent set of entry-points, and leaves the mode management up to the implementation of Filter. I'll happily make the changes and update the associated tests.

As a side note, I had a side-band discussion with @ethomson about how to handle the .gitattributes macros (example: [filter "lfs"] \n clean = git lfs clean %f \n smudge = git lfs smudge %f). While there are normal situations when you just know(tm) what to do on smudge and clean callbacks, ideally the filter would at least aware if the user has edited the values of the macro.

Assuming we can find a solution, whatever solution we'll find will likely end up impact this API. Perhaps then we should combine the two discussions here.

/CC @ammeep @shiftkey @nulltoken

[nulltoken]

This is very uneven

Can you please elaborate on that? This is a little... brief to me.

virtual void Apply(string root, string path, Stream input, Stream output, FilterMode mode)

Could you please describe the pros of this approach and the cons of the existing implementation?

[whoisj]

Can you please elaborate on that? This is a little... brief to me.

With Create we pass in the FilterMode, there's no CreateSmudge or CreateClean; and Complete we supply no information about Clean vs Smudge and assume the lib consumer knows what we mean.

I'm recommending that we pass FilterMode to the lib consumer so that they have as much information about the filter state as we can provide.

Could you please describe the pros of this approach and the cons of the existing implementation?

If all other entry-points (Create and Complete) are passing in the FilterMode instead of having unique per-mode entry-points, why do we treat write differently? With the write callback, we split it on the lib consumer. The Libgit2 API is a single callback - we've needlessly split it into two.

Maybe Apply is the wrong verb, maybe we should keep the verb Write? I used Apply because it made more sense to me to "apply a filter" than to "write a filter".

I'm open to suggestions.

[ethomson]

I wonder why a filter instance (for a file) isn't an instance of an object... It might be nice if instead of Createing a filtering instance on a long-lived Filter object, we had one per file. I can imagine that an instance of filtering a file would like to save some data, and it would be nice if there was encapsulation of that on a per-file basis. It's not real likely that you would have two filters executing simultaneously but this still seems possible (one thread doing a checkout, one thread just running a filter on a buffer...).

[whoisj]

I wonder why a filter instance (for a file) isn't an instance of an object... It's not real likely that you would have two filters executing simultaneously but this still seems possible (one thread doing a checkout, one thread just running a filter on a buffer...).

👍
This was my original assumption and line of questioning when I started this project. 😃

[nulltoken]

this still seems possible (one thread doing a checkout, one thread just running a filter on a buffer...).

I like this idea as well 👍

[whoisj]

I like this idea as well 👍

Great. I'll make this happen right after the holiday.

[whoisj]

@nulltoken @ethomson this happened in #1140