We should stop project-root pollution

09 October 2024

Not too long ago people realized that enough is enough and that programs should not be writing stuff directly to $HOME as they please. The battle is far from over, as many programs still hard-code their settings path, but the XDG Base Directory Spec has gained enough support to at least enable tools that automate the cleanup process.

What about our repositories, though?

A quick glance at BigQuery’s public datasets for GitHub data shows that many files at the project root are just configuration for some vendor or tool:

/* most common files at the root of GitHub repositories */
SELECT
  path,
  COUNT(*) as count
FROM `bigquery-public-data.github_repos.sample_files`
GROUP BY path
-- only top-level files, i.e. paths which don't contain slashes
HAVING path NOT LIKE '%/%'
ORDER BY count DESC
LIMIT 1000

(Remaining 975 rows at the bottom of the article.)

Some of those are understandably relevant to occupy real estate at the project root (README, LICENSE, CHANGELOG).

But many are just tool-specific configuration files, most of which rarely gets touched.

“Why do you care?”

Hey, I’m not the only one. I care because it gets noisy and cluttered. It makes even simple tasks, like finding the main package declaration, become frustrating for users who aren’t familiar with the language.

The project root is like a living room, and we should keep it tidy to make guests feel comfortable.