{"thread":{"id":"62938","subject":"[PATCH] doc: clarify the intent of the renormalize option in the merge machinery","startedAt":"2025-02-11T21:01:56Z","lastAt":"2025-02-12T06:18:27Z","messageCount":2,"participants":["Elijah Newren via GitGitGadget","Torsten Bögershausen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"512258","messageId":"pull.1861.git.1739307712372.gitgitgadget@gmail.com","threadId":"62938","inReplyTo":null,"subject":"[PATCH] doc: clarify the intent of the renormalize option in the merge machinery","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-02-11T21:01:52Z","receivedAt":"2025-02-11T21:01:56Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren <newren@gmail.com>\n\nThe -X renormalize (or merge.renormalize config) option is intended to\nreduce conflicts due to normalization of newer versions of history.  It\ndoes so by renormalizing files that it is about to do a three-way\ncontent merge on.  Some folks thought it would renormalize all files\nthroughout the tree, and the previous wording wasn't clear enough to\ndispell that misconception.  Update the docs to make it clear that the\nmerge machinery will only apply renormalization to files which need a\nthree-way content merge.\n\n(Technically, the merge machinery also does renormalization on\nmodify/delete conflicts, in order to see if the modification was merely\na normalization; if so, it can accept the delete and not report a\nconflict.  But it's not clear that this piece needs to be explained to\nusers, and trying to distinguish it might feel like splitting hairs and\novercomplicating the explanation, so we leave it out.)\n\nSigned-off-by: Elijah Newren <newren@gmail.com>\n---\n    doc: clarify the intent of the renormalize option in the merge machinery\n    \n    cf.\n    https://lore.kernel.org/git/CABPp-BGQ0pc=AZ0fdXcqDbhMLbm2xBvi71g0mXAVDagz19NkEg@mail.gmail.com/\n    and the thread there\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1861%2Fnewren%2Fclarify-renormalize-docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1861/newren/clarify-renormalize-docs-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1861\n\n Documentation/config/merge.txt     | 3 ++-\n Documentation/gitattributes.txt    | 4 ++--\n Documentation/merge-strategies.txt | 2 +-\n 3 files changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt\nindex 82554d65a0a..f6e50542baa 100644\n--- a/Documentation/config/merge.txt\n+++ b/Documentation/config/merge.txt\n@@ -69,7 +69,8 @@ merge.renormalize::\n \tTell Git that canonical representation of files in the\n \trepository has changed over time (e.g. earlier commits record\n \ttext files with CRLF line endings, but recent ones use LF line\n-\tendings).  In such a repository, Git can convert the data\n+\tendings).  In such a repository, for each file where a\n+\tthree-way content merge is needed, Git can convert the data\n \trecorded in commits to a canonical form before performing a\n \tmerge to reduce unnecessary conflicts.  For more information,\n \tsee section \"Merging branches with differing checkin/checkout\ndiff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\nindex e6150595af8..9ae81173003 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -701,8 +701,8 @@ where the attribute is not in place would normally cause merge\n conflicts.\n \n To prevent these unnecessary merge conflicts, Git can be told to run a\n-virtual check-out and check-in of all three stages of a file when\n-resolving a three-way merge by setting the `merge.renormalize`\n+virtual check-out and check-in of all three stages of each file that\n+needs a three-way content merge, by setting the `merge.renormalize`\n configuration variable.  This prevents changes caused by check-in\n conversion from causing spurious merge conflicts when a converted file\n is merged with an unconverted file.\ndiff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt\nindex 5fc54ec060b..a5dc95a3783 100644\n--- a/Documentation/merge-strategies.txt\n+++ b/Documentation/merge-strategies.txt\n@@ -56,7 +56,7 @@ ignore-cr-at-eol;;\n \n renormalize;;\n \tThis runs a virtual check-out and check-in of all three stages\n-\tof a file when resolving a three-way merge.  This option is\n+\tof any file which needs a three-way merge.  This option is\n \tmeant to be used when merging branches with different clean\n \tfilters or end-of-line normalization rules.  See \"Merging\n \tbranches with differing checkin/checkout attributes\" in\n\nbase-commit: fbe8d3079d4a96aeb4e4529cc93cc0043b759a05\n-- \ngitgitgadget\n"},{"id":"512294","messageId":"20250212061819.GB990@tb-raspi4","threadId":"62938","inReplyTo":"pull.1861.git.1739307712372.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: clarify the intent of the renormalize option in the merge machinery","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2025-02-12T06:18:19Z","receivedAt":"2025-02-12T06:18:27Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Tue, Feb 11, 2025 at 09:01:52PM +0000, Elijah Newren via GitGitGadget wrote:\n> From: Elijah Newren <newren@gmail.com>\n>\n> The -X renormalize (or merge.renormalize config) option is intended to\n> reduce conflicts due to normalization of newer versions of history.  It\n> does so by renormalizing files that it is about to do a three-way\n> content merge on.  Some folks thought it would renormalize all files\n> throughout the tree, and the previous wording wasn't clear enough to\n> dispell that misconception.  Update the docs to make it clear that the\n> merge machinery will only apply renormalization to files which need a\n> three-way content merge.\n>\n> (Technically, the merge machinery also does renormalization on\n> modify/delete conflicts, in order to see if the modification was merely\n> a normalization; if so, it can accept the delete and not report a\n> conflict.  But it's not clear that this piece needs to be explained to\n> users, and trying to distinguish it might feel like splitting hairs and\n> overcomplicating the explanation, so we leave it out.)\n>\n> Signed-off-by: Elijah Newren <newren@gmail.com>\n> ---\n>     doc: clarify the intent of the renormalize option in the merge machinery\n>\n>     cf.\n>     https://lore.kernel.org/git/CABPp-BGQ0pc=AZ0fdXcqDbhMLbm2xBvi71g0mXAVDagz19NkEg@mail.gmail.com/\n>     and the thread there\n\nMy first impression after reading this:\nThanks, that makes sense.\nThe second one: Do we need to explain how a merge works here in this\npart of the documenatation ?\n\nThe third round after re-reading and re-thinking:\n\nYes, this makes sense and lloks good.\n\n\n"}]}