🟢 Available for work

Why You Should Never Commit Compiled CSS and JS to Git

They look harmless.

They feel necessary.

But committing them to Git quietly introduces risk.

What are compiled files?

These files are generated automatically from the source code.

For example you might have some sass files called header.scss, nav.scss and fonts.scss but these are not referenced on the website themselves. They are used to compile a single, optimized main.css file that is used to style the site.

Some other examples:

  • Sass ➡️ CSS
  • Tailwind ➡️ CSS
  • TypeScript ➡️ JavaScript
  • ES modules ➡️ Bundled JavaScript
  • Minified assets (e.g. nav.js ➡️ nav.min.js)
  • Critical CSS
  • Build outputs

Simply: if a file is recreated automatically, it probably doesn’t belong in Git

Why teams commit them (and why it seems like a good idea)

There are a few common reasons that teams commit these files to the project reposititoies; I’ve either experienced these in agencies or used these myself.

1. “We deploy directly from Git”

This is probably the most common of the 3, and is most applicable for small/1-person teams. Why introduce additional complexity to what are probably simple web projects?

2. “It avoids running build tools on production”

Deploying to production can already be quite stressful, especially when you’re working with big-name clients or high-traffic sites. So adding an additional step might just feel like something else that can go wrong.

3. “We don’t have a pipeline yet”

Time is always a factor, especially if you’re working in an agency and every minute is accounted for. Setting up a pipeline might just seem like a luxury that you can’t afford.

These are all reasonable decisions, especially when the teams are small or projects are delegate one-per-developer. However, in the long run it’s still worth taking the time to setup build tools and pipelines to avoid pain later in life.

The problems compiled files cause

– Merge conflicts become more difficult to resolve

Compiled files change constantly. In fact, in some project every time you save your code the compiled code might change (sometimes dramatically).

Even small changes can generate large differences:

<<<<<<< HEAD
.main{margin:10px}
=======
.main{margin:12px}
>>>>>>> branch

This change is not an issue in itself, but 30,000 lines of code, minified — now this becomes a problem.

– Git history becomes harder to read

Occasionally you’ll be making commits that read like so:

Updated compiled assets

Which isn’t meaningful compare to something like

Fixed navigation bug with menu items alignment

This makes auditing and finding causes to issues a lot harder.

– Deployments become riskier

Reliability is important for any project, more so than convenience.

Commonly, failures can arrise through

  • Files being out of sync
  • Assets missing
  • Incorrect builds deploye

The correct method: treat compiled files as artifacts

Here’s the recommended flow;

  1. Developer writes code
  2. Source code is pushed to git repository
  3. Pipeline builds assets (e.g. compiled files)
  4. Deployed including compiled files or artifacts

This method creates consistent, predictable builds and provides a safer process for releases.

.gitignore is key

To make this method work, a well written .gitignore file is key. Typically you’d include some variation on the following

node_modules/
dist/
build/
*.min.css
*.min.js

When is it OK to commit compiled files

At the end of the day, this is about acceptable levels of risk; if introducing this modern approach to a project is high risk, then it might not be best to tackled lightly. Here’s a list of some scenarios where it’s OK to commit compiled files:

  • No build pipeline available
  • Static hosting environments
  • Legacy systems/high-risk projects

The TLDR;

Treat compiled assets as artifacts. Anything that is compiled should not be tracked in your git project and instead, should be generated automatically in your pipeline.

This will make your git workflow a lot simplier, safer, and more predicatable.

April 14th

2026
✍️ Blog AI

AI and Human Creativity: My Conflicted Thoughts on Artificial Intelligence

A personal reflection on artificial intelligence, creativity, and work—exploring fear, ethics, and why the human journey behind art still matters in the age of A.I.

Read more ->
AI and Human Creativity: My Conflicted Thoughts on Artificial Intelligence

March 24th

2026
✍️ Blog Development

How better CI/CD pipelines reduce client risk

Most deployment problems aren’t caused by code — they’re caused by the pipeline. Learn how better CI/CD pipelines reduce risk and create predictable, stable releases.

Read more ->
How better CI/CD pipelines reduce client risk

March 17th

2026
✍️ Blog

Why most WordPress load 1mb of unused CSS

Why a WordPress site loading unused CSS is an architecture problem, not a CSS one.

Read more ->
Why most WordPress load 1mb of unused CSS
See more moments ->
© 1985-2026 Carl Lister