doc: clarify the intent of the renormalize option in the merge machinery

The -X renormalize (or merge.renormalize config) option is intended to
reduce conflicts due to normalization of newer versions of history.  It
does so by renormalizing files that it is about to do a three-way
content merge on.  Some folks thought it would renormalize all files
throughout the tree, and the previous wording wasn't clear enough to
dispell that misconception.  Update the docs to make it clear that the
merge machinery will only apply renormalization to files which need a
three-way content merge.

(Technically, the merge machinery also does renormalization on
modify/delete conflicts, in order to see if the modification was merely
a normalization; if so, it can accept the delete and not report a
conflict.  But it's not clear that this piece needs to be explained to
users, and trying to distinguish it might feel like splitting hairs and
overcomplicating the explanation, so we leave it out.)

Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt
index 8851b6c..5806c1e 100644 (file)
--- a/Documentation/config/merge.txt
+++ b/Documentation/config/merge.txt
@@ -69,7 +69,8 @@ merge.renormalize::
        Tell Git that canonical representation of files in the
        repository has changed over time (e.g. earlier commits record
        text files with CRLF line endings, but recent ones use LF line
-       endings).  In such a repository, Git can convert the data
+       endings).  In such a repository, for each file where a
+       three-way content merge is needed, Git can convert the data
        recorded in commits to a canonical form before performing a
        merge to reduce unnecessary conflicts.  For more information,
        see section "Merging branches with differing checkin/checkout

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index e615059..9ae8117 100644 (file)
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -701,8 +701,8 @@ where the attribute is not in place would normally cause merge
 conflicts.
 
 To prevent these unnecessary merge conflicts, Git can be told to run a
-virtual check-out and check-in of all three stages of a file when
-resolving a three-way merge by setting the `merge.renormalize`
+virtual check-out and check-in of all three stages of each file that
+needs a three-way content merge, by setting the `merge.renormalize`
 configuration variable.  This prevents changes caused by check-in
 conversion from causing spurious merge conflicts when a converted file
 is merged with an unconverted file.

diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 5fc54ec..a5dc95a 100644 (file)
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -56,7 +56,7 @@ ignore-cr-at-eol;;
 
 renormalize;;
        This runs a virtual check-out and check-in of all three stages
-       of a file when resolving a three-way merge.  This option is
+       of any file which needs a three-way merge.  This option is
        meant to be used when merging branches with different clean
        filters or end-of-line normalization rules.  See "Merging
        branches with differing checkin/checkout attributes" in