doc: clarify the intent of the renormalize option in the merge machinery
PATCH 1/1 doc: clarify the intent of the renormalize option in the merge machinery
From: Elijah Newren <[email protected]>
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.)
---
doc: clarify the intent of the renormalize option in the merge machinery
cf.
https://lore.kernel.org/git/CABPp-BGQ0pc=AZ0fdXcqDbhMLbm2xBvi71g0mXAVDagz19NkEg@mail.gmail.com/
and the thread there
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1861%2Fnewren%2Fclarify-renormalize-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1861/newren/clarify-renormalize-docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1861
Documentation/config/merge.txt | 3 ++- Documentation/gitattributes.txt | 4 ++-- Documentation/merge-strategies.txt | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-)
Documentation/config/merge.txt +2 -1
@@ -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
Documentation/gitattributes.txt +2 -2
@@ -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.
Documentation/merge-strategies.txt +1 -1
@@ -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
base-commit: fbe8d3079d4a96aeb4e4529cc93cc0043b759a05
Signature · 1 line
gitgitgadget
Quoted 18 lines · Elijah Newren via GitGitGadget
From: Elijah Newren <[email protected]>
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.)
Quoted 7 lines
Signed-off-by Elijah Newren <[email protected]>---
doc: clarify the intent of the renormalize option in the merge machinerycf.
https://lore.kernel.org/git/CABPp-BGQ0pc=AZ0fdXcqDbhMLbm2xBvi71g0mXAVDagz19NkEg@mail.gmail.com/
and the thread there
My first impression after reading this:
Thanks, that makes sense.
The second one: Do we need to explain how a merge works here in this part of the documenatation ?
The third round after re-reading and re-thinking:
Yes, this makes sense and lloks good.