summaryrefslogtreecommitdiff
path: root/Documentation/gitattributes.txt
diff options
context:
space:
mode:
authorEyvind Bernhardsen <eyvind.bernhardsen@gmail.com>2010-07-02 19:20:47 (GMT)
committerJunio C Hamano <gitster@pobox.com>2010-07-02 22:43:15 (GMT)
commitf217f0e86dc7bacc5dc127982eaadca758b558ce (patch)
treeffd4e74f1b5fb99e6434351354487f2d08c039f3 /Documentation/gitattributes.txt
parent492b10766f499b60bdc867c253f36d274ac51538 (diff)
downloadgit-f217f0e86dc7bacc5dc127982eaadca758b558ce.zip
git-f217f0e86dc7bacc5dc127982eaadca758b558ce.tar.gz
git-f217f0e86dc7bacc5dc127982eaadca758b558ce.tar.bz2
Avoid conflicts when merging branches with mixed normalization
Currently, merging across changes in line ending normalization is painful since files containing CRLF will conflict with normalized files, even if the only difference between the two versions is the line endings. Additionally, any "real" merge conflicts that exist are obscured because every line in the file has a conflict. Assume you start out with a repo that has a lot of text files with CRLF checked in (A): o---C / \ A---B---D B: Add "* text=auto" to .gitattributes and normalize all files to LF-only C: Modify some of the text files D: Try to merge C You will get a ridiculous number of LF/CRLF conflicts when trying to merge C into D, since the repository contents for C are "wrong" wrt the new .gitattributes file. Fix ll-merge so that the "base", "theirs" and "ours" stages are passed through convert_to_worktree() and convert_to_git() before a three-way merge. This ensures that all three stages are normalized in the same way, removing from consideration differences that are only due to normalization. This feature is optional for now since it changes a low-level mechanism and is not necessary for the majority of users. The "merge.renormalize" config variable enables it. Signed-off-by: Eyvind Bernhardsen <eyvind.bernhardsen@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/gitattributes.txt')
-rw-r--r--Documentation/gitattributes.txt34
1 files changed, 34 insertions, 0 deletions
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 564586b..da553ff 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -317,6 +317,17 @@ command is "cat").
smudge = cat
------------------------
+For best results, `clean` should not alter its output further if it is
+run twice ("clean->clean" should be equivalent to "clean"), and
+multiple `smudge` commands should not alter `clean`'s output
+("smudge->smudge->clean" should be equivalent to "clean"). See the
+section on merging below.
+
+The "indent" filter is well-behaved in this regard: it will not modify
+input that is already correctly indented. In this case, the lack of a
+smudge filter means that the clean filter _must_ accept its own output
+without modifying it.
+
Interaction between checkin/checkout attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -331,6 +342,29 @@ In the check-out codepath, the blob content is first converted
with `text`, and then `ident` and fed to `filter`.
+Merging branches with differing checkin/checkout attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have added attributes to a file that cause the canonical
+repository format for that file to change, such as adding a
+clean/smudge filter or text/eol/ident attributes, merging anything
+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`
+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.
+
+As long as a "smudge->clean" results in the same output as a "clean"
+even on files that are already smudged, this strategy will
+automatically resolve all filter-related conflicts. Filters that do
+not act in this way may cause additional merge conflicts that must be
+resolved manually.
+
+
Generating diff text
~~~~~~~~~~~~~~~~~~~~