@matheusbsbs / matheus-bagliano / commits / 45761988ac

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>

Elijah Newren committed Feb 11, 2025 at 21:01 UTC 45761988ac01b99f9a81ad6ec884bef3c2d8e402

3 files changed +5 -4

Documentation/config/merge.txt

+2 -1

@@ -69,7 +69,8 @@ merge.renormalize::

69 Tell Git that canonical representation of files in the

70 repository has changed over time (e.g. earlier commits record

71 text files with CRLF line endings, but recent ones use LF line

72 - endings). In such a repository, Git can convert the data

72 + endings). In such a repository, for each file where a

73 + three-way content merge is needed, Git can convert the data

74 recorded in commits to a canonical form before performing a

75 merge to reduce unnecessary conflicts. For more information,

76 see section "Merging branches with differing checkin/checkout

Documentation/gitattributes.txt

+2 -2

@@ -701,8 +701,8 @@ where the attribute is not in place would normally cause merge

701 conflicts.

702

703 To prevent these unnecessary merge conflicts, Git can be told to run a

704 -virtual check-out and check-in of all three stages of a file when

705 -resolving a three-way merge by setting the `merge.renormalize`

704 +virtual check-out and check-in of all three stages of each file that

705 +needs a three-way content merge, by setting the `merge.renormalize`

706 configuration variable. This prevents changes caused by check-in

707 conversion from causing spurious merge conflicts when a converted file

708 is merged with an unconverted file.

Documentation/merge-strategies.txt

+1 -1

@@ -56,7 +56,7 @@ ignore-cr-at-eol;;

57 renormalize;;

58 This runs a virtual check-out and check-in of all three stages

59 - of a file when resolving a three-way merge. This option is

59 + of any file which needs a three-way merge. This option is

60 meant to be used when merging branches with different clean

61 filters or end-of-line normalization rules. See "Merging

62 branches with differing checkin/checkout attributes" in