Create .gitattributes

[DoctorDerek]

This .gitattributes file will force Windows developers to check out LF line endings instead of the default "auto" behavior (CRLF check out, LF check in).

This is a quality-of-life improvement for Windows developers, who will otherwise need to manually fix line endings after forking the repository in order to avoid ESLint (prettier/prettier) line ending errors ("Remove CR").

References:
https://git-scm.com/docs/gitattributes#_end_of_line_conversion
https://dev.to/deadlybyte/please-add-gitattributes-to-your-git-repository-1jld#gitattributes-reset

[codecov-io]

Codecov Report

Merging #3760 (8a79c8d) into master (4754bfe) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #3760   +/-   ##
=======================================
  Coverage   93.34%   93.34%           
=======================================
  Files         178      178           
  Lines        1849     1849           
  Branches      332      332           
=======================================
  Hits         1726     1726           
  Misses        105      105           
  Partials       18       18           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4754bfe...8a79c8d. Read the comment docs.

[adamwathan]

Hey thanks! I don't know much about this stuff — what would be the difference between what you've suggested here and what React does for example?

facebook/react@8abca77

[DoctorDerek]

Comparison with React .gitattributes file

Hey thanks @adamwathan and @danny007in 😀

So that Facebook example (facebook/react@8abca77) is actually the default behavior for Git repositories hosted at GitHub, which means their .gitattributes file really doesn't do anything. The line endings are going to get normalized when pushing origin. (Reference at end)

That confused the **** out of me, but all that happens is:

1. GitHub only accepts LF line endings on their server unless told otherwise by the .gitattributes file.
2. *nix / Mac developers get LF line endings as you'd expect.
3. Windows developers will get CRLF (system preference) locally when pulling from origin, but they'll still push LF endings.

Current behavior and Windows workflow

Here's the current behavior for /tailwindlabs/tailwindcss when I clone it on Windows 10 using GitHub Desktop, after npm install:

As you can see, every file has ESLint errors that come from the "prettier/prettier" rule in the .estlint.json file in this repo. The line endings setting is currently only explicitly set in ".editorconfig" -- and that roduces conflicts for developers like myself who use Prettier on all files, which is why I opened #3713 to add a Prettier config file.

That PR won't fix the screenshot issue, though, leaving me two options as a Windows developer:

1. Run npm run style --fix . (per contributing.md) and then create an empty commit before starting.
2. Make my VS Code's default Prettier settings match those specified in .eslint.json and .editorconfig match yours, format the file manually, and create the empty commit before starting. (Merging Add Prettier configuration file (prettier.config.js) #3713 would reduce that workflow to just formatting the file)

Effects of this PR

Merging this PR (#3760) and adding .gitattributes would mean that I don't get the CR/LF line endings at all, so there is no error. I can't take a screenshot of cloning from my branch, so I duplicated the project into a new Git repo.

I published that to GitHub, deleted my local copy, and recloned it from doctorderek/tailwindcss-gitattributes-demo ... followed by npm install :

As you can see, I might still have some local errors based on my VS Code settings (in this case, TypeScript warnings), but I pull down on Windows with the correct line endings.

Other ways of achieving this PR

You could remove and/or tweak the ESLint rule prettier/prettier, but that seems like a big change to accommodate Windows developers when adding the .gitattributes file will fix it.

Hope this explanation helps!

Reference

"If you want to ensure that text files that any contributor introduces to the repository have their line endings normalized, you can set the text attribute to 'auto' for all files. * text=auto" Source: https://git-scm.com/docs/gitattributes#_text

[DoctorDerek]

I updated the .gitattributes file to explicitly avoid changing binary files, based on best practices from https://gitattributes.io/

## Source: https://github.com/alexkaratarakis/gitattributes
## Modified * text=auto to * text eol=lf to force LF endings.

## GITATTRIBUTES FOR WEB PROJECTS
#
# These settings are for any web project.
#
# Details per file setting:
#   text    These files should be normalized (i.e. convert CRLF to LF).
#   binary  These files are binary and should be left untouched.
#
# Note that binary is a macro for -text -diff.
######################################################################

# Auto detect
##   Force LF line endings automatically for files detected as
##   text and leave all files detected as binary untouched.
##   This will handle all files NOT defined below.
*                 text eol=lf

The new .gitattributes file continues on for about 200 lines total while achieving the same result:

Windows developers will have LF line endings for text files, meaning they will not see ESLint "prettier/prettier" errors.

This improved .gitattributes file prevents corrupting binary files (e.g. .png or .woff), which can happen if git finds a false "CRLF" inside their binary code. Just ask my Vercel deploy about that 😄

Comparison with previous .gitattributes file

Compared to the default * text=auto setting, which results in Windows users checking out text files with CRLF line endings, the * text eol=lf setting results in LF line endings on Windows (the desired behavior per eslintrc.json).

However, a one-line .gitattributes file that only includes * text eol=lf tells git to treat all files as text, which can corrupt committed binary files.

Since there's no "auto" mode, it's left to the owner of the git repo to explicitly specify every possible non-text file -- which is why the best practice around line endings is to use a .gitattributes file specific for your type of project.

This updated .gitattributes file is a slightly modified version of the open-source, community-maintained "Web Project" .gitattributes file by @alexkaratarkis from @alexkaratarakis/gitattributes ... Thank you to the contributors.

Further Reading / References

1. https://gitattributes.io/ and https://github.com/alexkaratarakis/gitattributes
2. https://www.edwardthomson.com/blog/advent_day_1_gitattributes_for_text_files.html
3. https://markoskon.com/line-endings-in-vscode-with-git-and-eslint/

[samarmohan]

Are we going to merge this because I use Windows and the eslint line-break problem is really bugging me.

[DoctorDerek]

I found manually running `eslint . --fix` works OK as a workaround, unless you want to switch branches. Or maybe just edit the eslint config file to remove the rule while you're working on it, then don't commit that change. Just some thoughts 😊 Those red squiggly lines drive me crazy too haha.

[DoctorDerek]

Hey @samarmohan I feel you 😀 I think @adamwathan was leaning towards "not merge" but of course it makes sense that this is a low priority for the @tailwindlabs team. This PR is still in fact open, and I've been having good success using a thorough .gitattributes file in my other professional work.

[reinink]

Hey @DoctorDerek, I really appreciate you taking the time to put this PR together and also thoroughly explaining what it does. And while there is clearly a challenge here for Windows developers, pulling in a 200 line PR like this is a bit scary for us, because it will become our job to maintain it moving forward, and, as you can probably tell, no one on the Tailwind Labs team uses Windows for development.

Given that, and since it sounds like you have a viable workaround (thanks for sharing that!), I am going to close this issue.

Thanks either way for the contribution and for your interest in Tailwind CSS 💪