[PATCH] Clarify text filter merge conflict reduction docs

From

Eyvind Bernhardsen <eyvind.bernhardsen@gmail.com>

Date

Jun 28, 2010, 19:32 UTC

Message-ID

<0cd82ad22a6f240ebcde0c2f3a437a805dae5668.1277753114.git.eyvind.bernhardsen@gmail.com>

In-Reply-To

<20100628080234.GA7134@pvv.org>

Signed-off-by: Eyvind Bernhardsen <eyvind.bernhardsen@gmail.com>
---
How does this look?

- Eyvind

 Documentation/gitattributes.txt |   46 ++++++++++++++++++++++-----------------
 1 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index b110082..22400c1 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -317,17 +317,16 @@ 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.
+For best results, `clean` should not alter its output further if it is
+run twice ("clean->clean" should be equivalent to "clean"), and
+multiple `smudge` commands should not alter `clean`'s output
+("smudge->smudge->clean" should be equivalent to "clean").  See the
+section on merging below.
 
-The example "indent" filter is well-behaved in this regard: it will
-accept input that is already correctly indented without modifying it.
-In this case, the lack of a smudge filter means that the clean filter
-_must_ accept its own output without modifying it.
+The "indent" filter is well-behaved in this regard: it will not modify
+input that is already correctly indented.  In this case, the lack of a
+smudge filter means that the clean filter _must_ accept its own output
+without modifying it.
 
 
 Interaction between checkin/checkout attributes
@@ -346,16 +345,23 @@ with `text`, and then `ident` and fed to `filter`.
 Merging branches with differing checkin/checkout attributes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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.
-
-This strategy will break down if a `smudge` filter relies on its input
-having been processed by the corresponding `clean` filter or vice
-versa.  Such filters may otherwise work well, but will prevent
-automatic merging.
+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
+where the attribute is not in place would normally cause merge
+conflicts.
+
+To prevent these 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.
+
+As long as a "smudge->clean" results in the same output as a "clean"
+even on files that are already smudged, this strategy will
+automatically resolve all filter-related conflicts.  Filters that do
+not act in this way may cause additional merge conflicts that must be
+resolved manually.
 
 
 Generating diff text

-- 
1.7.1.575.g383de