It's not configuration though. Specifically, it's not configuration of the project in question, it's configuration for third party accessories.
If I'm writing an editor, I expect the config directory in the source code to hold the configuration for the editor, not .babelrc
meta is a much better name and they are "about" the project, not the project itself, so I disagree on that point. Though I agree it should not be hidden. I will start having a "meta" directory in my projects
But third party accessories are an essential part of any project these days, they aren't optional or afterthoughts. In that page they mention docker-compose.yml as once example. Most likely it's impossible (in its current state) to actually run that application without Docker.
Other things that would land in the folder:
- Files essential to building the project
- Files essential to running the test suite
- Files essential to developing on the project
IMO a "project" includes all those things. In your definition are those all "meta"? Does "meta" mean anything that's not source code?
The name doesn't make sense, those aren't metadata files, they're configuration or application.
I guess I'm also not seeing what the exact problem is. The project root is crowded, yes, now this suggests making a different directory crowded. The messiness is shifted.
Let’s not bikeshed this. The most common use of the meta prefix means “about (this category)”, eg metadata, but that’s not its only form.
The original Greek prefix is a preposition that means “with”, “among”, or “beside”. Doesn’t seem like a stretch that config files are a type of metafile.
I don't understand how that is an argument. Of course organizing things involves moving them to other places. That is basically the definition of organizing something.
By that logic, why put any files in directories? Let's keep the entire project at the root level.
The truth is, it's not that the current project roots are a mess. It's that there's a complete and holistic category of file that is being kept in the root of projects, and putting them in a directory dedicated to that category is utterly sensible. Every other category is kept in a dedicated namespace in the file structure, why should config files be the exception?
But that’s still better than not moving the clutter at all. A root directory with important files + clutter is worse then a root directly with only important files and a separate directory with clutter.
I agree with the GP about bikeshedding. A debate about this would never end.
Which is why the whole thing needs to be nipped in the bud.
For one thing .meta would already be a dotfile so .dotfile/.env would be redundant. But that's called dotenv! What's it going to be named now? Or maybe that wouldn't be included. But it's on the list in the tweet linked to in the article.
This entire thing already feels like a bike shedding exercise. I agree it’s kind of uncomfortable. But I’ve had no real problems over the years of having these files in whatever directory they need to be in given the context they work for.
I kinda like the status quo. I like seeing all the tooling artifacts at the top level when I open a GitHub repo or something, it’s nice to see at a glance - like a quick digest of what is used to develop that software. And they all are hidden automatically in a local file browser, so it’s not like it’s really a mess. And the .prefix means they don’t mess up tab completion.
It’s the ones that arent hidden that are a problem, and if they’re already obnoxious enough to choose a non-hidden file name they’re probably not going to support a hidden directory either - Dockerfile, Jenkinsfile, and bitbucket-compose.yml, I’m looking at you.
> I like seeing all the tooling artifacts at the top level when I open a GitHub repo or something, it’s nice to see at a glance - like a quick digest of what is used to develop that software.
I agree with this proposal that it can be a mess, but hiding the files or directories isn’t a solution. Instead, the mess we often see reflects the abysmal unification of tooling in modern software development, and the JS ecosystem is perhaps the worst offender.
If things suck, let them fester in the open air. Stuffing them away isn’t gonna fix the mess, just sweep it under the rug.
I must say though, that one huge pet peeve that I have, is software that don’t allow projects to be rooted in a subdir of the git repo root. This is a huge annoyance when you work with multiple stacks in the same project.
I tend to agree. The reason these files land in the root directory of many repos is because the multitude of tools that use them expect their file to be in $PWD, and running make or mvn or docker or npm from the root of the repo is usually convenient. Changing that paradigm needs more of a justification than tidiness, I think.
For most of these repo-specific config, if you put it in a subdirectory then some tooling won't work properly. If your dockerfile is in ops/, the you have to tell people how to run docker build. If your .eslintrc is in ops/, then those rules will only apply to files in subdirectories of ops/...
Yeah it's certainly tradeoff, especially for the rc-type files that get auto-detected by editors.
Still, I feel like the status quo is pretty good. Most ecosystems have built in task runners for specifying/documenting commands, js and python projects can opt to shove a lot of config in package.json or pyproject.toml for a lot of ecosystem tooling respectively if they want (similar for a lot of languages).
i know this goes down the rabbit hole, but i think every project benefits from a makefile or other taskrunner file. even if a project is a simple “docker build ...” having done task makes it really easy to see
"or other taskrunner file" is the problem, because to some approximation npm or docker are task runners.
The presence of a makefile at the top level tells you you can run make. The presence of a dockerfile tells you you can build with docker. It's not a good system, but it kinda works.
no, a makefile with a docker build task acts as a reference for how to build the image. that’s my point.
_any_ repo has clues about the toolchain encoded in the file types and extensions, but that’s not the same thing.
and yes, npm or yarn can define scripts which can have the same documentation benefits. but there’s lots of others too that are specifically for tasks. i really like https://taskfile.dev.
these files can communicate how to work in a project.
The onus is on the tools developers to adopt this change. And the proposal allows for the gradual, graceful migration from current status to a place where all such files are stored in a central location.
The directory name `.toolsconfig`, or `.tc` is the best I could recommend, since `config` or `.config` can be safely assumed to be already in use. Using 'tools' in the directory name also makes it explicit as to whose config files are stored in there; tools developers use, not the config of the projecct itself.
Edit: The Git repo of the proposal is hosted on Github. Feel free to propose any changes or improvements to the proposal or the algorithm.
I don't like "tc" because it is not self-explanatory and somewhat cryptic to me. The argument on name collisions is valid, although even "toolsconfig" is not 100 % safe.
Hiding files under a directory is not really a solution for anything other than slightly improving file navigation, but even if you think it's valuable, the real problem is getting tools to adopt it. There is no incentive to be the first. The intermediate state is terrible - now you need to guess if a config is located at the root or this new config directory, and if your version of the tooling is able to pick up the new location.
I think this is a good concept, and I'd like to offer some feedback.
Things I like:
- I agree that something should be done
- I think having a wall of honor on your site is a good way to promote adoption
- I think you make some good arguments
Things I question:
- .meta - As others have pointed out, it's not metadata about the project, it's part of the project. Also, as others have noted, having this be a dot file will unnecessarily hide the directory in some circumstances.
- There is no org-based namespacing in the .meta approach
- A wall of honor is probably not enough to drive adoption
Recommendations:
- I think another form of adoption driver is to discuss it on the mailing lists of 2-3 large open source projects, get them to buy into you submitting a PR for this as a non-breaking enhancement (if files not found in current dirs, look in .meta; if files not found at all create them in .meta), and then follow through with the PR for each. Some candidates are VS Code, NPM, NetBeans, Maven, and Cargo.
- etc seems a natural project config directory name. /etc is for system config files, ${BASEDIR}/etc is for project config files. There may be some conflicts here with projects already using etc, but the file's should conflict.
- what I think we need is a unified project metadata file, then links in that file could be traversed to the tool specific files and it wouldn't matter where they were - they wouldn't need to be in the root directory. Description of a Project (DOAP) [1] was a good start toward this, but the last time it had more than 1 PR a year was in 2018. There's no JSON format.
> This is avoid making a mess in the root directory of projects, as [this] tweet laments.
Registered an entire domain name to back an idea based on a tweet, but completely missing the point of that tweet. If only they'd read the tweeter's own replies under that same tweet they could've avoided wasting their time on this.
For clarity: the original tweeter was bemoaning the state of JS tooling (the busy root directory being a symptom - not the core problem). Throwing your fifty config files in a hidden subdirectory is what's typically referred to as "supporting dysfunction".
- A lot of files they mention aren't random metadata but critical parts of the project. Stuff like package.json, Dockerfile, build configs etc. should not be hidden away.
- For a lot of other files like .git, .gitignore, .dockerignore their exact path matters to their operation, especially since a lot of them are hierarchical as well.
The author's sole problem seems to be that their project root is too cluttered, and some people here have a better suggestion - fix it at the UI layer instead. Have VS Code (or whatever other file browser) automatically put these files in a virtual sub-folder.
This is such a great idea. I kind of hate all the top level clutter in my repos and it seems to get worse every year. Wonderful suggestion. Whether it’s .meta, .config or .etc I don’t really care.
It's generally really well respected by a lot of software. It's just not well known enough that its annoying. In my experience a lot of the failures are from Apple developers assuming that this is a "Linux spec".
The XDG spec appears to be specifying user-wide/system-wide configuration files, but the post is about organizing files specific to an individual project or repository.
IMO this should be more aggressive in a few ways, not the least being it should invert the fallback logic. It should also include some obvious non-config meta-stuff, ie every top level Markdown/plain text file save maybe README.
Lastly, I think part of the reason this problem is so annoying to warrant it is that lots of tools think they’re so special that they need to create a new config even when they create redundancies with other overlapping config content. I know this is a “there are N competing standards” proclamation, but it would be nice if same-ecosystem tools were encouraged to collaborate on config specs/schemas so a great deal more stuff could be defined once, in one format, at one well-known path.
> It should also include some obvious non-config meta-stuff, ie every top level Markdown/plain text file save maybe README.
The problem you're trying to solve with this is just related to the fact that README starts with R. In the past, I've been an advocate for breaking with tradition and naming your README "ABOUT" instead.
> it would be nice if same-ecosystem tools were encouraged to collaborate on config specs/schemas so a great deal more stuff could be defined once, in one format, at one well-known path
Or better: thinking long and hard about the question "What problem is this trying to solve?" and then considering whether another tool that dumps/reads a config file at a fixed location is the best way to deal with it in the first place.
Instead of attempting to change ALL tools to accept a config file in a non-standard location which is never going to happen, and will just lead to having files in both locations, just recode the file browsers to optionally display config files under a virtual directory. There’s surely fewer file browsers than tools.
I actually have an extension that adds a little expandable section called "Hidden Files" at the bottom of the explorer pane, where I can open it and add a check beside the files I want to hide. In some projects, I change it at leisure, which usually means I'm hiding any files that never have any bearing on my day to day work. Sorry I don't remember the exact name of the extension.
I prefer $PROJ/config/ (or even /settings/) -- this is self-explanatory. $PROJ/.meta is not a standard practice and would be confusing (what's so meta?). Why use dotfile naming? That's just old practice that no longer needs to be used. We're not hiding anything (and why should we?). Configurations should never be hidden.
I feel like the main reason why dotfiles exist is because they typically got put in your $HOME and that would just litter your file manager's view.
That's at least some sort of organization (which drawer?), this just hides the mess with no organization.
If you're gonna propose tidying it up, at least propose a useful organization other than just hiding it, like from the example list of files maybe something like 3 subdirectories: installers, linters, and compilers/runners?
Well, presumably the root directory of a code repo does contains drawers (directories) other than ".meta/", e.g. sources in "src/", headers in "include/", assets in "assets/", etc.
I think the point of ".meta" is the drawer for config files of _tools_. And these tools, depending on the language and the ecosystem, might not fall into neat subdirectories like "installers", or "linters". Some compiler comes with their own packaging system, and some with their own linter.
".meta/{tool_name}.{ext}" or ".meta/{tool_name}/*.{ext}" should be sufficient in that regard. (Though I do prefer ".config" over ".meta")
In my closet there is a bin full of batteries. This bin has no internal organization; all different types of batteries are jumbled together. You could say that I have just hidden the mess, and that there is no point having a battery bin unless you are also going to have a sub-bin for each type of battery - but in practice, this is enough. When I need a battery, I know where to look for it, and there are no batteries cluttering up any other parts of my house.
Because the most important part of the problem isn't the profusion of config files, it's that as a project owner I'm not in control of the most important entry point to my own work.
The alternative for a lot of things is the root directory having almost nothing in it, because the main content is already split from the top level directory by:
- node monorepos by putting everything in the packages directory
- python repos by putting almost everything underneath the name of the package
What might help some who are annoyed by this perceived clutter is to be to jump straight into the main content in the subdirectory. Getting the other files moved out only helps it a little because you don't have to go through as many items to click or cd into the main content's directory. It doesn't remove a whole step. The steps are still 1) to go to the repo and 2) click or cd to the directory that has the main content.
This pattern is also sometimes called a doom box. They're useful for when you need to make forward progress on task #1 (tidying the desktop) but don't have the energy to do task #2 (actually deal with the random crap).
Having the proposed directory actually named "mess" is probably a much better idea than a semi-respectable sounding name like ".meta". A constant reminder that most of this stuff is a joke to begin with—that "none of this is necessary; it is merely customary", as Jef Raskin once put it—wouldn't be the worst thing in the world.
It'd probably make a lot more sense for it to be called `.config/`, amongst all other things, but for this to gain any traction at all, some bigger projects need to show initiative first. Everything already has like 47 potential config file names they read, so adding another one won't put a dent into the schedule
".config" seems like such a natural name for it that I assumed it must be taken by some other program so they couldn't use it. I would expect a ".meta" folder to hold things like release history, a graph of the number of files in the project over time, links to external design documents, and other facts "about" the project. Not config files used by the project.
It kind of is... There is a formal standard that everyone ignores called XDG which defines the ".config" directory along with a few other handy common ones.
The XDG base directory specification defines a .config directory for user-specific configuration files (e.g. tmux.conf, i3's config file, a global gitignore file). This proposed standard would be for project-specific configuration files (e.g. a project-local .gitignore, .dir-locals.el, .mypy.ini).
I do think .etc would be a pleasantly smart way to blend with the rest of the world as it exists.
This case isn't covered by XDG, but there's a path here we probably could & should adapt, that suggests itself. And this forges off in a new direction.
> ~/.local (standard? convention?) which simply mimics the filesystem root with bin,etc,include etc.
That's not the filesystem root, is it? From what I can tell, ~/.local mimics `/usr`; it has bin and include, yes, but also `share`, and no `/etc` that I'm aware of. `/` does have `bin`, but I don't think I've ever seen `include` there on a system before.
It's a little weird because presumably repos shouldn't just be a .local folder. We'd still be excepting the actual source from this.
Maybe we just use a FileSystem Heirarchy pattern for repos? Many projects already have source in src/. Move all the build config stuff into a etc/ in the project, no .anything/?
The XDG standard covers most of these as well. Cached data that is safe to delete? There is a directory for that. Runtime data that needs to live as long as the instance of the app? Directory for that. External data your app might rely on but contains no user data? Directory for that.
It's very flexible and widely accepted. It's just not accepted _enough_ to be annoying.
At least a couple of them are unambiguously programs (despite being defined in config formats). And many of the others are configs which allow program formats, which could hypothetically do arbitrary program things as well.
There are other top level files which I’d want to include if I were the one designing this, many of which are just text/reference, all of which are inherently meta content relative to their containing project. It may well even be worth nesting sub-category directories below .meta, eg .meta/config or even .meta/config/{checks,env,…}. I’m sure some would consider any/all of this overkill, but the current status quo of top-level junk is certainly no better than a tree with well defined and well named branches.
Back in the day, this is what /etc was for. You'd install binaries in /usr or /bin and then NFS mount those from your clients. Then all the config was local in /etc (and the programs generally respected the idea of either creating a config file in /etc on first run or just doing the default thing if it wasn't there).
I'm sad that we got away from that standard. It was nice when I could just back up /etc and be good to go.
(Of course this is looking with rose colored glasses, we never had 100% adherence to the standard, which is how we got to where we are).
Most of the examples they give - like package.json - are specific to the project, not the whole operating system. And they are typically checked in to a project’s git directory.
/etc stores system configuration (like the local timezone). They have a very different purpose.
That's incorrect, those are system config (i.e. how nginx/httpd run on your system). Which is a very different type of config than being discussed here.
You seem to be thinking of programs, this is talking about projects. Various compilers, linkers, CI tools, etc. look in the root directory of your project for config files or other rules. This proposes to move all those files to `.meta` in order to keep the project root directory clean.
> Would this also apply to home directory, eg ~/.meta/.netrc? That would be neat and make backing up a system and synching configs easier.
~/.config and ~/.local already exist for that purpose: applications should read and store configuration in ~/.config, use ~/.local/share for data, and install binaries to ~/.local/bin.
What about yard - "yet another root directory", if naming matters?
The term also has a meaning that "an area ... used for a special purpose". As you may use your back "yard" tidying your households from time to time, it is quite aligned with the idea of .meta directory - tidying things up?
Even better would be to have tools share configuration files. Plain make files don't have this problem. Build scripts also don't have this sort of problem. Ofc once you start with autotools, things go pretty bad. Build scripts usually suck once a project is larger than a toy. Golang has an interesting approach.
This is such a dejavu, I remember a few years ago someone made the same initiative and succeeded to get a lot of repos/projects to place all their dotfiles in one folder, but I do not remember the name of the folder... anyone?
As an excuse to try mapping out a debate in some depth, I set up a Discussion, “Should software projects adopt a standard subdirectory for files for configuration, tools, & metadata?”[1] on kialo.com, that others can explore or add to.
If this was implemented, what kinds of files would have the privilege to live at the root of the project?
In case it's just folders left, the root folder as a location for project-scoped configuration files still has the advantage that nobody has to look for it?
We already have language-specific files to define those keys, such as `package.json`, `pyproject.toml`, `Cargo.toml`, `deno.json` (and many more).
I don't see why you shouldn't integrate it into your project configuration instead of pretending that _'this is fine'_ and hiding all of it in a directory.
This already exists. Why you are reinventing the wheel again?!?
A lot of programs already implement the XDG Base Directory Specification[1], putting the configuration in the .config directory. These programs should just follow the ALREADY EXISTING specification.
If you want to understand it, the arch wiki[2] have a good explanation about all the directories.
This proposal calls for developers to adopt a standard within their projects, as opposed to addressing where configuration files for installed software should live within a user's home directory.
This site exists to advocate that software libraries look for their config files in .meta directories of projects.
This is avoid making a mess in the root directory of projects, as this tweet laments.
## Basics
The XDG Base Directory Specification is based on the following concepts:
- There is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME.
On having it start with a dot: Why? Why would we pretend that these crucial files don't exist?
On having it named meta: These files aren't "about" the project or "above" the project, they ARE the project.