Line ending configuration in Git

When you work with people on different OS systems, you probably run into line-ending (CRLF or LF) issues. Git provides different ways to control line ending style to help you with this issue.

For a quick view, there are two ways to set your line ending style. core.autocrlf is a global setting that is configured by git config command. The configuration file where core.autocrlf is set into is not committed into the repository. Using Git attributes is a per-repository setting. The attributes are written in a file named .gitatribute that can be committed into the repository and overrides core.autocrlf , ensuring an consistent behavior of different users regardless of their Git settings.

Git configuration variable — core.autocrlf

core.autocrlf is a Git configuration variable that you can set with git config for all repositories or for a specific repository. It can be set with one of the three following values: true, input and false.

However, experiments for Git v2.13.2 on Windows show different effect with what is declared in git config.

According git config:

  • “core.autocrlf” is set to “true”

    Git will convert LF to CRLF when checking out text files. When committing text files, CRLF will be converted to LF.

  • “core.autocrlf” is set to “input”

    Git will not perform any conversion when checking out text files. When committing text files, CRLF wiil be converted to LF.

  • “core.autocrlf” is set to “false”

    Git will not perform any conversions when checking out or committing text files.

Experiments for Git v2.13.2 on Windows show:

  • true, convert LF to CRLF on commit, convert LF to CRLF on checkout if the file has been committed with LF and it does not exist in the working directory.
    $ git config core.autocrlf true
    
    $ git add eol-lf.txt
    warning: LF will be replaced by CRLF in eol-lf.txt.
    The file will have its original line endings in your working directory.
    
  • input, convert CRLF to LF on commit, convert CRLF to LF on checkout if the file has been committed with CRLF and it does not exist in the working directory.
    $ git config core.autocrlf input
    
    $ git add eol-crlf.txt
    warning: CRLF will be replaced by LF in eol-crlf.txt.
    The file will have its original line endings in your working directory.
    
  • false, no convert on commit.

Therefore test that on your machine and decide how to set core.autocrlf.

Examples

# Set core.autocrlf to true globally
$ git config --global core.autocrlf true

# Config core.autocrlf to input locally for the current repository
$ git config core.autocrlf input

Note: Git configuration file is not committed into the repository, but .gitattributes file can be committed.

Git attributes — text and eol

text and eol are two attributes that can help to set your line ending style in .gitattribute file.

There are some inconsistence description for text and eol in Configuring Git to handle line endings (from github.com) and .gitattributes file (from gitscm.org). And after some experiments the first documentation seems to be the right one. According to this doc, the effects of the two attributes are:

text=auto

  • Git will handle the files in whatever way it thinks is best. This is a good default option.

text eol=crlf

  • Git will always convert line endings to CRLF on checkout. You should use this for files that must keep CRLF endings, even on OSX or Linux.

text eol=lf

  • Git will always convert line endings to LF on checkout. You should use this for files that must keep LF endings, even on Windows.

binary

  • Git will understand that the files specified are not text, and it should not try to change them. The binary setting is also an alias for -text -diff.

Example from Configuring Git to handle line endings

Here’s an example .gitattributes file. You can use it as a template for your repositories:


# Set the default behavior, in case people don't have core.autocrlf set. * text=auto # Explicitly declare text files you want to always be normalized and converted # to native line endings on checkout. *.c text *.h text # Declare files that will always have CRLF line endings on checkout. *.sln text eol=crlf # Denote all files that are truly binary and should not be modified. *.png binary *.jpg binary

Note: A .gitattributes file can be located in any directory of a repository which takes effect to content of that folder and its sub folders.

Refresh a repository after changing line endings

If you have committed files with wrong CRLF/LF line endings. You can forcibly to add tracked files again to the index even they are unmodified after changing core.autocrl or text attribute.

# Suppose you have committed file with wrong CRLF/LF line endings.

# Now:
# Change `core.autocrlf` or `text` attribute for your desired line ending style.

# Execute `git add` with --renormalize option
$ git add --renormalize .
Show the rewritten, normalized files.

# Show what happed
$ git status

# Commit the changes to your repository.
$ git commit -m "Normalize all the line endings"

Resources

Configuring Git to handle line endings

core.autocrlf

  • Git configuration

  • git config

    Note: The experiments with core.autocrlf on Windows give different results with below description.

    core.autocrlf

    Setting this variable to “true” is the same as setting the text attribute to “auto” on all files and core.eol to “crlf”. Set to true if you want to have CRLF line endings in your working directory and the repository has LF line endings. This variable can be set to input, in which case no output conversion is performed.

Git attributes