If you look at a git repository for some software project, you’ll probably notice that the root folder is littered with tons of files. You don’t just have a README and a bunch of folders. You may see things like pyproject.toml for Python projects, .Rproj for R, Makefile or build.ninja for build systems, .pre-commit-config.yaml for pre-commit checks, .vscode/ or .eclipse/ for code editors, etc. As projects grow in complexity, the root of a git repository becomes overwhelming.
Personally, I think this is a problem. Instead of seeing files and folders that reflect the structure of the code and a gentle onboarding for new users, I see a cluttered garage with all the tools and blueprints an engineer needs obstructing the entryway. It feels like a lack of care and organiza…
If you look at a git repository for some software project, you’ll probably notice that the root folder is littered with tons of files. You don’t just have a README and a bunch of folders. You may see things like pyproject.toml for Python projects, .Rproj for R, Makefile or build.ninja for build systems, .pre-commit-config.yaml for pre-commit checks, .vscode/ or .eclipse/ for code editors, etc. As projects grow in complexity, the root of a git repository becomes overwhelming.
Personally, I think this is a problem. Instead of seeing files and folders that reflect the structure of the code and a gentle onboarding for new users, I see a cluttered garage with all the tools and blueprints an engineer needs obstructing the entryway. It feels like a lack of care and organization, but this is not the user’s fault - this clutter stems from how the tools are designed. What I find interesting about this problem is that it’s not a new one. We’ve already encountered this problem before and we already have a solution.
In earlier days of computing, when programs needed to store files on your computer, there were no rules. This was especially bad on Linux, where some tools would put files in /usr/, some in /etc/, and others right in your $HOME directory. There are many legitimate reasons why this happened, many of them having to do with disk partitions, desktop environments, and limited storage in decades prior.
This annoyed many users. It was hard to find files they needed to configure their tools properly and their $HOME directory became littered with files they didn’t make or want. It felt a tad disrespectful, having all these guests leave your $HOME in such disarray 1.
Thankfully, a bunch of people recognized the problem and set out to fix it. That work resulted in the X Desktop Group’s (XDG) Base Directory Specification. It’s a simple description of what kinds of files should go where and tons of tools use it 2. It’s great. If you make some software that stores files on a user’s device, you should follow this spec. And better yet, there are libraries like dirs (Rust), xdg (Go), and many others in your programming language of choice to help you easily follow the spec.
I would love to see this same thinking applied to software that operates on repositories. At the project’s root you place a .config/ folder and configuration files for the entire project go in there. Then the rest of your repository is structured the way you think it should be structured.
I’m not the only one who feels this way. Dot-config promotes this idea and was created by others years ago. As the page says, this is not a new standard, not a new tool, it’s just common sense.
While the XDG spec has lots of libraries to help developers follow the spec, I can’t find any libraries that do this for project directories. Maybe this is something someone could bash together at a hackathon. Or maybe it’s something I should try as a fun little project. Either way, I’d love to see tidier project directories and I think dot-config is an idea that can enable that.
Footnotes
See What is $HOME to you? or Defending $HOME for more opinions. ↩ 1.
As always, the Arch Linux Wiki has a great summary of the spec, as well as a table of what software supports the spec. ↩
Comments on Mastodon.