Bug: Tailwind CSS Fails to Scan Files Without Git Initialization (git init)

[peixin]

What version of Tailwind CSS are you using?
v4.1.8 (confirmed unrelated to the issue)

What build tool (or framework if it abstracts the build tool) are you using?
Next.js 14.2.3 / Vite 6.3.5 (confirmed unrelated to the issue)

What version of Node.js are you using?
v22.16.1

What browser are you using?
Chrome / Firefox (confirmed unrelated to the issue)

What operating system are you using?
macOS 15.4.1

Reproduction URL
N/A (confirmed unrelated to the issue)

Describe your issue
When initializing a new project, Tailwind CSS fails to properly scan class names in files if git init hasn't been executed. The generated @layer utilities; remains empty despite containing valid Tailwind classes in the files. The issue is immediately resolved after running git init.

Reproduction Steps (Verified using official tools)

All steps folow the official installation guide: https://tailwindcss.com/docs/installation

Expected Behavior

Tailwind should scan files and generate utilities regardless of Git repository initialization status.

[wongjn]

Consider checking if you have some .gitignore higher up the file system tree. Any gitignore rules (including in .git/info/exclude) in higher folders could be applying to your project. Initializing a git repository acts as a boundary that stops searching higher up folders for these rules.

[peixin]

Yes, my Mac home directory is actually a Git repository that I use to back up common configuration files. This repository ignores all files by default, with specific exceptions configured for files like .zshrc and others. This makes the root cause clear.

The challenge was that I never expected Tailwind's functionality to be affected by Git configurations, especially in unrelated directories. This unexpected connection made the issue particularly difficult to diagnose, and I spent four full days troubleshooting it.

[RobinMalfait]

Hey!

The .git / .gitignore parts are the default behavior for our automatic content detection logic. We use this default because it's the most common setup for most projects. More info on how we scan files: https://tailwindcss.com/docs/detecting-classes-in-source-files#which-files-are-scanned

You can opt-out of this behavior explicitly https://tailwindcss.com/docs/detecting-classes-in-source-files#disabling-automatic-detection which should do the trick for you.

Tailwind should scan files and generate utilities regardless of Git repository initialization status.

This should still work, but if you have a .gitignore higher up the tree then that will be used. The main reason we have this is because some boilerplates do ship with a .gitignore file that contains node_modules and other files/folders and we should still skip those even if you didn't run .git.

These are all just trade-offs and we had to make a decision and pick a good default. Since most projects live in git repos, that is the better default.

So I wouldn't consider this a bug, and I would still recommend to run git init for your project though.

Hope this helps!