| Message ID | pull.1861.git.1739307712372.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 45761988ac01b99f9a81ad6ec884bef3c2d8e402 |
| Headers | show |
| Series | doc: clarify the intent of the renormalize option in the merge machinery | expand |
On Tue, Feb 11, 2025 at 09:01:52PM +0000, Elijah Newren via GitGitGadget wrote: > From: Elijah Newren <newren@gmail.com> > > 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> > --- > 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 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.
diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 82554d65a0a..f6e50542baa 100644 --- 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 e6150595af8..9ae81173003 100644 --- 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 5fc54ec060b..a5dc95a3783 100644 --- 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