I'm having trouble understanding the documentation. According to git-config(1):

core.eol

Sets the line ending type to use in the working directory for files that are marked as text (either by having the text attribute set, or by having text=auto and Git auto-detecting the contents as text). Alternatives are lf, crlf and native, which uses the platform's native line ending. The default value is native. See gitattributes[5] for more information on end-of-line conversion. Note that this value is ignored if core.autocrlf is set to true or input.

and gitattributes(5):

eol

This attribute marks a path to use a specific line-ending style in the working tree when it is checked out. It has effect only if text or text=auto is set (see above), but specifying eol automatically sets text if text was left unspecified.

Set to string value "crlf"

This setting converts the file's line endings in the working directory to CRLF when the file is checked out.

Set to string value "lf"

This setting uses the same line endings in the working directory as in the index when the file is checked out.

Unspecified

If the eol attribute is unspecified for a file, its line endings in the working directory are determined by the core.autocrlf or core.eol configuration variable (see the definitions of those options in git-config[1]). If text is set but neither of those variables is, the default is eol=crlf on Windows and eol=lf on all other platforms.

It's not clear to me what it means to "set the line ending type to use in the working directory" or to "mark a path to use a specific line-ending style in the working tree when it is checked out", and how this affects Git's behavior.

Given that "this value is ignored if core.autocrlf is set to true or input", that means it's only relevant when core.autocrlf = false, but doesn't core.autocrlf = false tell Git not to change line endings at all (according to How to change line-ending settings? In that case, since Git checks out and commits files as is, what is the point of setting core.eol?

I'm having trouble understanding the documentation. According to git-config(1):

core.eol

Sets the line ending type to use in the working directory for files that are marked as text (either by having the text attribute set, or by having text=auto and Git auto-detecting the contents as text). Alternatives are lf, crlf and native, which uses the platform's native line ending. The default value is native. See gitattributes[5] for more information on end-of-line conversion. Note that this value is ignored if core.autocrlf is set to true or input.

and gitattributes(5):

eol

This attribute marks a path to use a specific line-ending style in the working tree when it is checked out. It has effect only if text or text=auto is set (see above), but specifying eol automatically sets text if text was left unspecified.

Set to string value "crlf"

This setting converts the file's line endings in the working directory to CRLF when the file is checked out.

Set to string value "lf"

This setting uses the same line endings in the working directory as in the index when the file is checked out.

Unspecified

If the eol attribute is unspecified for a file, its line endings in the working directory are determined by the core.autocrlf or core.eol configuration variable (see the definitions of those options in git-config[1]). If text is set but neither of those variables is, the default is eol=crlf on Windows and eol=lf on all other platforms.

It's not clear to me what it means to "set the line ending type to use in the working directory" or to "mark a path to use a specific line-ending style in the working tree when it is checked out", and how this affects Git's behavior.

Given that "this value is ignored if core.autocrlf is set to true or input", that means it's only relevant when core.autocrlf = false, but doesn't core.autocrlf = false tell Git not to change line endings at all (according to How to change line-ending settings? In that case, since Git checks out and commits files as is, what is the point of setting core.eol?

• git
• carriage-return
• git-config
• linefeed
• core.autocrlf

Share Improve this question Follow edited Mar 8 at 9:34 dani-vta 7,53577 gold badges4949 silver badges6565 bronze badges asked Mar 8 at 2:05 ban_javascriptban_javascript 34511 gold badge55 silver badges1616 bronze badges 3

• Your misquote of the gitattributes docs might be the source of your trouble: the attribute is just eol. I fixed it. Read it again: attributes are pattern-matched and assigned per file; the config setting core.eol is a per-repo default. – jthill Commented Mar 8 at 2:32
• @jthill I must have made a mistake while formatting it, thanks for catching that! But yes I do understand that attributes apply to files and config to repos as defaults...my question is still: What does setting this do? For what does Git use this information? – ban_javascript Commented Mar 8 at 6:52
• Relevant questions/answers I've come across: stackoverflow/q/42340043 stackoverflow/q/3206843 stackoverflow/q/9976986 – ban_javascript Commented Mar 10 at 12:53

Add a comment  | 

2 Answers 2

Sorted by: Reset to default 0

With the core.autocrlf override sledgehammer turned off, core.eol sets the repo-local default for worktree newlines for files the attributes or Git's internal default autodetect say are text files. Git doesn't have to care whether they're being used as separators or terminators, for text files it just translates LF in repository content to whatever core.eol or any overrides say they should look like in the checkout.

---

There are multiple coding conventions for line endings even in plain ASCII and there are tools that only understand one of those conventions. So when working on your source, people using one OS can be wedded to a tool that only understands CRLF line endings, but on a different os there might be people who need a different one, not every team uses every tool…

So Git supports a convention for in-repository eol, plain LF, and supports converting those newlines on checkout to whatever the local tools need, then converting them back to its internally-blessed LF convention on add. git config is always repo-local; attributes can be a mix, tied to the history via a tracked .gitattributes and/or locally overridden in a .git/info/attributes (plus there's per-user and per-install defaults).

Git doesn't know without being told what files need this special handling, and it doesn't know whether they always need it, which can vary depending even on who's doing the checkout, and why. So yeah, Git wants to cater to automating any particular local setup and the controls for this get a bit fiddly.

One of the things confusing this already-mixed-up situation is, there's also two conventions for whether newlines are line separators or line terminators. That's why it's spelled "eol" and not "nl" or "newline": Git caters to the terminator convention.

To answer your questions, I think it's best to start with a brief digression on Git's internal structure.

Every non-bare repository has an object store and a working directory. The object store is Git's database which stores blobs (files), trees, commits, and tags. While the working directory is the folder where your changes are progressively added and recorded on top of the commit currently checked out.

The files that you have in the object store and the working directory (on checkout) not always correspond. Imagine a repository that is worked on from different platforms, for example a Linux and a Windows machine. When working on Linux, files are introduced with LF as their line endings, while on Windows with CRLF. In this scenario, every time a file is checked out on Windows, it would have the wrong line ending, preventing the system from reading the content correctly. However, here is where the attribute core.eol comes in to play. Its default value (native) prompts Git to automatically convert on checkout every end of line to the system's line ending, despite being stored in the object store differently (only when core.autocrlf is set to false). However, in order for core.eol to take effect, files need to be marked as text (either by having the text attribute set, or by having text=auto). This means that you repo should define a .gitattributes with the file types you wish to automatically convert.

For example, if you wish for your repo to automatically convert the end of line of every cpp file to the system's line ending, you should define a .gitattributes with the following entry:

*.cpp    text

---

A different setup to work from different platforms (non based on .gitattributes and patterns) is via autocrlf (overwriting core.eol). In this scenario, autocrlf is set to true on Windows machines, while to input on Linux-based systems. The object store contains only files with LF as their line ending. On Windows machines, end of lines would be automatically converted to CRLF at checkout, while to LF when recorded in the object store. Instead, on Linux machines, line endings would never be converted, leaving them to LF for both the object store and the working directory.