About line endings
Every time you press return on your keyboard you insert an invisible character called a line ending. Different operating systems handle line endings differently.
When you're collaborating on projects with Git and GitHub, Git might produce unexpected results if, for example, you're working on a Windows machine, and your collaborator has made a change in macOS.
You can configure Git to handle line endings automatically so you can collaborate effectively with people who use different operating systems.
Global settings for line endings
git config core.autocrlf command is used to change how Git handles line endings. It takes a single argument.
On macOS, you simply pass
input to the configuration. For example:
$ git config --global core.autocrlf input # Configure Git to ensure line endings in files you checkout are correct for macOS
On Windows, you simply pass
true to the configuration. For example:
$ git config --global core.autocrlf true # Configure Git to ensure line endings in files you checkout are correct for Windows. # For compatibility, line endings are converted to Unix style when you commit files.
On Linux, you simply pass
input to the configuration. For example:
$ git config --global core.autocrlf input # Configure Git to ensure line endings in files you checkout are correct for Linux
Optionally, you can configure a .gitattributes file to manage how Git reads line endings in a specific repository. When you commit this file to a repository, it overrides the
core.autocrlf setting for all repository contributors. This ensures consistent behavior for all users, regardless of their Git settings and environment.
The .gitattributes file must be created in the root of the repository and committed like any other file.
A .gitattributes file looks like a table with two columns:
- On the left is the file name for Git to match.
- On the right is the line ending configuration that Git should use for those files.
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
You'll notice that files are matched—
*.png—, separated by a space, then given a setting—
binary. We'll go over some possible settings below.
text=autoGit will handle the files in whatever way it thinks is best. This is a good default option.
text eol=crlfGit will always convert line endings to
CRLFon checkout. You should use this for files that must keep
CRLFendings, even on OSX or Linux.
text eol=lfGit will always convert line endings to
LFon checkout. You should use this for files that must keep LF endings, even on Windows.
binaryGit will understand that the files specified are not text, and it should not try to change them. The
binarysetting is also an alias for
Refreshing a repository after changing line endings
When you set the
core.autocrlf option or commit a .gitattributes file, you may find that Git reports changes to files that you have not modified. Git has changed line endings to match your new configuration.
To ensure that all the line endings in your repository match your new configuration, backup your files with Git, delete all files in your repository (except the
.git directory), then restore the files all at once.
- Save your current files in Git, so that none of your work is lost.
$ git add . -u $ git commit -m "Saving files before refreshing line endings"
- Add all your changed files back and normalize the line endings.
$ git add --renormalize .
- Show the rewritten, normalized files.
$ git status
- Commit the changes to your repository.
$ git commit -m "Normalize all the line endings"
- Customizing Git - Git Attributes in the Pro Git book
- git-config in the man pages for Git
- Getting Started - First-Time Git Setup in the Pro Git book
- Mind the End of Your Line by Tim Clem