Git line endings can differ between repository storage and checked-out files according to attributes and configuration. A shared project needs a deliberate policy so developers do not repeatedly create large formatting-only diffs or break scripts on another platform. The right rule depends on file type and the tools that consume it.
This guide explains text detection, eol attributes, normalization, and migration. The aim is consistent reviewed content, not forcing every file through the same conversion regardless of its actual format.
Separate stored content from checkout form
A repository can store normalized text while producing a platform-appropriate working-tree representation. These are related but distinct states. A file’s visible line endings on one machine do not fully explain what Git records.
Review the effective attributes and relevant Git configuration. Local and system settings can interact with repository rules. A developer’s global preference should not be the only specification for a cross-platform project.
Document which files require LF, CRLF, or no conversion. Shell scripts and particular platform-specific project files can have different needs. Choose the policy from supported tooling and execution behavior.
Use repository attributes for shared rules
A .gitattributes file can express file-type-specific text and eol behavior that travels with the project. This is easier to review than relying solely on each developer to reproduce undocumented local settings.
Use patterns narrow enough to match intended files. A broad rule can affect generated assets or formats that should remain untouched. Review attribute precedence and nested attribute files when troubleshooting unexpected behavior.
Keep the policy simple and explain unusual exceptions. A long collection of conflicting patterns can make checkout behavior hard to predict. Explicit ownership helps future contributors understand why a rule exists.
Distinguish text from binary content
Automatic text detection can be convenient, but some files need explicit classification. Binary or specialized formats should not be normalized simply because a tool guessed they looked textual.
Set an appropriate no-text-conversion rule for formats that require byte preservation. Test representative files after checkout and round-trip operations. A file that remains present may still have corrupted content.
Do not classify sensitive artifacts as safe merely because conversion is disabled. Attribute rules control handling, not permission or secret exposure. Binary fixtures and archives still need the normal repository-data review.
Apply eol rules to actual consumers
An eol attribute chooses the intended working-tree line-ending form for supported text handling. Check the script interpreter, editor, build tool, or external application that reads the file.
Avoid converting everything to CRLF or LF as a symbolic platform preference. The practical requirement is whether the supported consumer behaves correctly and whether developers obtain stable diffs.
Test on the supported operating systems. A Linux build can miss a Windows-specific tool issue, while a Windows editor can silently rewrite a file that a Unix interpreter needs differently. Cross-platform acceptance should reflect the project.
Renormalize in an isolated change
Introducing attributes does not always rewrite every existing tracked file automatically. A deliberate renormalization step may be needed. Use the supported Git workflow from a clean, preserved working state.
Keep normalization separate from feature changes where practical. Reviewers should not have to distinguish a one-line behavior change from thousands of line-ending replacements in the same commit.
Inspect the staged changes before committing. Exclude files that should not be normalized by correcting their attributes and restaging appropriately. Do not assume a broad renormalize command correctly classified every artifact.
Preserve local work before migration
A repository-wide content-handling change can affect many tracked files. Commit or otherwise preserve unrelated edits and check the preservation scope before starting. Avoid running a migration over a working tree full of valuable unsaved changes.
Coordinate with collaborators who maintain long-running branches. A normalization commit can increase merge noise and conflicts. Record the migration point and explain how the team should update its branches through the normal workflow.
Do not rewrite published history just to make older commits look normalized unless a separate explicitly approved migration requires it. A forward normalization commit usually preserves a clearer collaboration boundary.
Check filters and generated artifacts separately
Other Git attributes can configure filters, diff handling, or merge behavior. These mechanisms can interact with how a file appears in the working tree, but they are not all line-ending controls.
Review LFS-managed files and generated content through their own supported rules. A repository with pointer files and external artifacts needs more than a generic text policy. Confirm exact artifact availability and byte integrity separately.
Keep generated formatting reproducible through approved tools. If generation rewrites endings unpredictably, fix the generation workflow rather than repeatedly accepting noisy diffs. The policy should agree with how files are produced.
Diagnose differences with evidence
Inspect effective attributes for the affected path and compare staged versus working-tree state. Check whether the editor, a formatter, or a Git conversion caused the change. Do not begin by deleting every local configuration setting.
Use controlled representative files to test checkout and add behavior. Include a script, a normal text document, and a binary fixture. This makes it easier to identify which rule is responsible.
A clean status after checkout is useful, but also run relevant tools and verify bytes where preservation matters. Clean repository state is not proof that an external consumer accepts the selected representation.
Maintain the policy as the project grows
Review new file formats and tooling with the repository’s content rules. An added build system can introduce files with a different requirement. Update attributes in the same reviewed workflow as that dependency.
Include practical guidance for contributors about editors and formatting checks. A repository policy is stronger when the development environment supports it rather than constantly fighting it.
For a project with Unix scripts and Windows project files, explicit attributes and a separate renormalization commit can reduce repeated churn. The lasting benefit comes from consistent tooling and tests, not from a one-time mass conversion alone.
Frequently asked questions
Does a local autocrlf setting define the whole team policy?
No. Shared repository attributes and actual consumer requirements should be reviewed together.
Should binary files be normalized as text?
No. Use appropriate rules to preserve formats that require exact bytes.
Where are precedence and normalization examples documented?
Read the Git attributes reference for text, eol, and renormalization behavior.
For a complementary workflow, read Git LFS: Pointer Files, Artifact Access and Recovery.
