Git for Windows: Line Endings
If you’re on a team of Windows developers - or more importantly, on a cross-platform development team - one of the things that comes up constantly is line endings. Your line ending settings can be the difference between development productivity and constant frustration.
The key to dealing with line endings is to make sure your configuration is
committed to the repository, using .gitattributes
. For most people,
this is as simple as creating a file named .gitattributes
at the root
of your repository that contains one line:
* text=auto
With this set, Windows users will have text files converted from Windows
style line endings (\r\n
) to Unix style line endings (\n
) when they’re
added to the repository.
If you're bored already, you can probably stop reading right now. For most developers - in most repositories - this is all you need to know.
Why not core.autocrlf
?
Originally, Git for Windows introduced a different approach for line
endings that you may have seen: core.autocrlf
. This is a similar
approach to the attributes mechanism: the idea is that a Windows user
will set a Git configuration option core.autocrlf=true
and their
line endings will be converted to Unix style line endings when they add
files to the repository.
The difference between these two options is subtle, but critical: the
.gitattributes
is set in the repository, so its shared with everybody.
But core.autocrlf
is set in the local Git configuration. That means
that everybody has to remember to set it, and set it identically.
The first, best option you have to get this right is when you’re installing Git for Windows:
You probably want the first option, but you’d be forgiven if you didn’t know that the first time you ran the installer.
The problem with core.autocrlf
is that if some people have it set to
true
and some don’t, you’ll get a mix of line endings in your repository.
And that’s not good - because his setting doesn’t just tell Git what you
want it to do with files going in to your repository. It also tells Git
what you’ve already done, and what the line endings look like on the files
that are already checked in.
This is why one of the most common symptoms of a line ending configuration
problem is seeing “phantom changes”: running git status
tells you that
you’ve changed a file, but running git diff
doesn’t show you any changes.
How can that be? Line endings.
Phantom Changes
Imagine that some file is checked in to your repository with Windows-style
line endings. For some reason, somebody hadn't set core.autocrlf=true
when they added the file. You, on the other hand, being a diligent Git
for Windows user, did set that option.
When you run git status
, git will look at that file to decide whether
you've made any changes to it. When it compares what's on disk to what's
in your repository, it will convert the line endings on-disk from
Windows-style style to Unix-style in the repository. Since the existing
file in the repository had Windows-style line endings, and you expect them
to be Unix style, git will determine that the file is different. (It is,
byte for byte, different.)
By using .gitattributes
, you ensure that these settings exist at the
repository level, instead of leaving it up to individual users to
understand to configure correctly. This means there’s no opportunity
for misconfiguration by an individual user.
Of course, the best time to set this up is at the very moment you create your repository, before you add any files. Doing it after the fact means that you may still have some files added with the wrong configuration.
Over time, these files will be updated as you edit them. You can try to renormalize files, updating the line endings, but doing so will cause annoying merge conflicts for anybody who created a branch before the renormalization.
What About Binaries?
Generally speaking, git is pretty good at detecting whether a file is a binary or not. If it decides that a file is a binary, then it will refuse to convert line endings. But it's still good practice to configure git not to convert line endings for your binary files.
You can remove the text
attribute from files that you don't want to have
line ending conversions. For example, if you have PNGs in your repository,
your .gitattributes
might look like this:
* text=auto
*.png -text
Of course, there are more advanced settings in your
.gitattributes
that can be applied. These are especially useful in particular development scenarios. We'll dive deeper into some of those - like using Unity - in the next blog post.