How to handle line endings in git

Andreas Löw
How to handle line endings in git

Who is this tutorial for?

This tutorial is for all developers who use git on different platforms such as Windows, macOS and Linux.

How we handle line endings in our tools

Our tools TexturePacker, PhysicsEditor and BabelEdit always write line endings according to the operating system they work on.

This ensures that the files can be opened by every editor on that platform without the need of converting the files.

When working cross-platform, e.g. on Windows and macOS, with a version management system such as git, this might not work out of the box.

We assume that you set your version management system to work with local file endings. With this the version management system ensures that the files are correctly checked out and in.

git can handle file endings on global, per-repository and file type base.

Global line endings setup for git

Windows

On Windows, you should use these settings if you are also working with a Mac or a Linux machine: They check all files in with a line feed (LF) and check them out with carriage-return line feed (CRLF):

git config --global core.autocrlf true

If you are only working on Windows you can also check-in CRLF by disabling the feature:

git config --global core.autocrlf false

macOS and Linux

The usual setting for these 2 operating systems is input:

git config --global core.autocrlf input

With this setting, files are checked out as they are. Checking files in converts them with CRLF endings to LF.

Per-repository settings

If you don't want to change your global settings, you can also use per-repository settings by adding a .gitattributes file:

# 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

Each line consists of file name pattern - e.g. *.c - followed by the instruction how this file should be treated:

  • text=auto Let git decide.
  • text eol=crlf Force CRLF on checkout - no matter what operating system is used.
  • text eol=lf Force LF on checkout - no matter what operating system is used.
  • binary Keep files as they are.

Refreshing your repository

When you either change the core.autocrlf setting or modify your .gitattributes you should perform the following operations to make a single change for all files instead of small changes scattered across many commits:

Save your files

Make sure to check in all your changed files... or revert them as needed:

git add . -u
git commit -m "Saving files before lineending change"

Change the line endings

Let git convert the files according to your line ending settings:

git add --renormalize .

Check in your updated files

Check the changed files in with a single commit:

git commit -m "Normalized line endings"