Re: [PATCH v4 1/3] Avoid conflicts when merging branches with mixed normalization

[Finn Arne Gangstad <finnag@pvv.org>]

> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -317,6 +317,18 @@ command is "cat").
>  	smudge = cat
>  ------------------------
>  
> +For best results, `clean` and `smudge` commands should produce output
> +that is not dependent on the corresponding command having been run.
> +That is, `clean` should produce identical output whether its input has
> +been run through `smudge` or not, and `smudge` should not rely on its
> +input having been run through `clean`.  See the section on merging
> +below for a rationale.

I think this is marginally unclear, what about:

  Clean should not alter its output further if run again
  clean(x) == clean(clean(x))

  Smudge should not alter the output of clean
  clean(x) == clean(smudge(x))

It should not matter that smudge will do something weird if clean
hasn't been run, as long as clean(x) == clean(smudge(x)) still
holds. I also think it is worth mentioning explicitly that clean can
be run multiple times, you should not have to infer this.

> [...]
> +Merging branches with differing checkin/checkout attributes
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Maybe something about when this happens, or even put it in the header
instead? Something like

  If you have added attributes to a file that cause the canonical
  repository format for that file to change, such as adding a
  clean/smudge filter or text/eol/ident attributes, merging anything based
  on a point in time where the attribute was not in place would normally
  cause merge conflicts.

> +
> +To prevent unnecessary merge conflicts, git runs a virtual check-out
> +and check-in of all three stages of a file when resolving a three-way
> +merge.  This prevents changes caused by check-in conversion from
> +causing spurious merge conflicts when a converted file is merged with
> +an unconverted file.


- Finn Arne