Ignoring line endings when using Git

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


When working with Git in an environment where developers use different operating systems, handling line endings can become tricky. Line endings refer to the characters used to mark the end of a line in text files, and they vary between Windows (CRLF or \r\n) and Unix-like systems such as Linux and macOS (LF or \n). This guide will explore how to configure Git to handle line endings properly, ensuring a smooth workflow across different environments.

Before diving into configurations, it's important to understand the terms:

  • CRLF: Carriage return and line feed, used by Windows.
  • LF: Line feed, used by Unix-based systems.
  • EOL (End Of Line): Refers to the marker at the end of each line.

Git provides several settings that help manage how line endings are handled in your repository. These settings can be applied globally (for all your projects) or on a per-repository basis.

  1. Setting up a global .gitconfig for line endings

    To ensure consistent line endings in all your repositories, you can configure Git globally:

    Terminal
    git config --global core.autocrlf true

    This command sets Git to:

    • Automatically convert LF to CRLF when you check out code on a Windows machine.
    • Convert CRLF back to LF when changes are staged (added to the index).

    On Unix-based systems, you might use:

    Terminal
    git config --global core.autocrlf input

    This setting converts CRLF to LF on commit but does not change LF to CRLF when checking out code, which is usually not necessary on Unix-like systems.

  2. Repository-specific configuration

    Sometimes, you might need to override global settings for a specific project. This is useful when the project has specific requirements or when contributing to projects with their own predefined line ending configurations.

    Navigate to your project directory in your terminal and run:

    Terminal
    git config core.autocrlf true

    This command applies the line ending configuration only to the current repository.

  3. Handling .gitattributes for finer control

    A .gitattributes file in your repository allows you to define rules that override both local and global Git configurations. Here's how to set up a .gitattributes file to manage line endings:

    • Create a .gitattributes file in the root directory of your repository:

      Terminal
      * text=auto
    • This configuration ensures that all files detected as text will have their line endings normalized when added to the repository. When these files are checked out, Git will apply the appropriate line endings for the OS.

  4. Dealing with existing repository files

    If your repository already has files with mixed line endings, you can normalize them:

    Terminal
    git add --renormalize .

    This command re-normalizes all files in the repository based on the current settings in .gitconfig or .gitattributes.

  5. Checking configuration

    To verify your configurations, use:

    Terminal
    git config --get core.autocrlf

    This command displays the current core.autocrlf setting for your project.

  • Consistency: Always aim for consistent line ending configurations across your development team to avoid unnecessary diffs and merge conflicts.
  • Documentation: Document your line ending policies in project READMEs or contribution guidelines to inform new contributors.
  • Tooling: Some editors and IDEs might have their own settings for handling line endings. Ensure these settings are aligned with your Git configuration to prevent conflicts.

For further reading on how Git handles line endings see the official Git documentation.

On this page
Git gud
"It's the first Git workflow I've used that actually feels good."
–@robboclancy
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2