Git .gitattributes and Line Ending Normalization

A .gitignore entry controls whether an otherwise untracked path is normally offered for adding. It does not define how an already tracked file's content should be stored. A .gitattributes entry assigns attributes to matching paths, including text handling, diff behavior and filters. Committing either file makes its rules available to collaborators, but their jobs are different. A binary asset is not automatically ignored because you mark it as binary. Likewise, an ignored filename does not become LF-normalized merely because it appears in an ignore pattern. Choose the appropriate mechanism for the actual requirement.

With text normalization enabled, Git stores normalized text with LF line endings in the index and commits. The eol attribute determines the intended working-tree ending at checkout for matching text paths. An eol=lf rule requests LF; eol=crlf requests CRLF. Your current working file may not immediately change just because an attribute file was edited or staged. Inspect the state instead of assuming a policy declaration already rewrote every byte on disk. Global and local configuration also interact with unspecified attributes, which is why a deliberate repository rule helps reduce machine-dependent surprises.

A practical policy might start with automatic text detection and then declare known script or data formats explicitly. Shell scripts often need LF endings; Windows command files can have a CRLF policy. Mark binary formats so text conversion is not applied to their content. Automatic detection is convenient but should not replace your knowledge of a format, especially for files with unusual byte patterns. Attribute patterns are path rules with their own documented matching behavior. Test representative files from each category and keep exceptions visible rather than depending on every contributor's editor guessing the same policy.

Git ls-files --eol displays ending information for tracked index entries and working files, together with effective text attributes. The exact spacing is a display detail; the important distinction is i/lf versus w/crlf and the attribute rule. Git show :path reads staged content, which can differ from the working file after normalization. When reviewing a suspicious diff, inspect both the content change and the file's ending state. A warning that CRLF will be replaced is not necessarily corruption, but it should agree with an intentional policy instead of being dismissed without understanding why it appeared.

Before running git add --renormalize, start from a understood working state, review the new attributes and account for any existing edits. The command reapplies relevant clean handling to tracked content; it is not a substitute for reading the resulting cached diff. Make normalization a focused commit so reviewers can distinguish byte-policy changes from behavior changes. Avoid combining a broad conversion with a feature refactor. Check your build and representative scripts afterward, because format-specific requirements still matter. Untracked files require their own staging decision and should not be assumed to have joined the normalization commit automatically.

Editor settings can make a repository policy easier to follow, but Git attributes and an editor's file-writing preferences remain separate mechanisms. Align the formatter, generated-file process and editor configuration with the committed rules. If a generator rewrites a text file every build, inspect whether its ending convention matches the policy before blaming Git for noisy diffs. Consider file encoding too: line endings do not determine whether a file is UTF-8 or another representation. A clear contribution note should identify the intended format and a small verification command rather than requiring contributors to guess which warning to suppress.

Review history and ignore rules, tracked files and configuration. Read the official attribute reference, add and renormalize behavior, file inspection and configuration reference.