doc: clarify the intent of the renormalize option in the merge machinery #1861
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 <[email protected]>
|
/submit |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
|
This patch series was integrated into seen via git@0c9c979. |
|
This patch series was integrated into seen via git@66dba55. |
|
On the Git mailing list, Torsten Bögershausen wrote (reply to this): On Tue, Feb 11, 2025 at 09:01:52PM +0000, Elijah Newren via GitGitGadget wrote:
> 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.)
>
> Signed-off-by: Elijah Newren <[email protected]>
> ---
> 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.
|
|
User |
|
This branch is now known as |
|
This patch series was integrated into seen via git@50a05b6. |
|
This patch series was integrated into seen via git@1ec5006. |
|
This patch series was integrated into next via git@2069f48. |
|
This patch series was integrated into seen via git@3b55445. |
|
There was a status update in the "Cooking" section about the branch Doc updates. Will merge to 'master'. source: <[email protected]> |
|
This patch series was integrated into seen via git@ddc2d23. |
|
There was a status update in the "Cooking" section about the branch Doc updates. Will merge to 'master'. source: <[email protected]> |
|
This patch series was integrated into seen via git@de6274b. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
cf. https://lore.kernel.org/git/CABPp-BGQ0pc=AZ0fdXcqDbhMLbm2xBvi71g0mXAVDagz19NkEg@mail.gmail.com/ and the thread there
cc: Torsten Bögershausen [email protected]