When it comes to organizing source code repositories, there are broad similarities — source code in
src/, tests in
test/ — but no universal standards. Recently I was thinking about this and wondered “What about UNIX?”
Most Linux distributions follow the Filesystem Hierarchy Standard to some extent. The directory names are short and familiar. The structure was even organized around how files change.
What would this look like applied to a project repository? Starting with the usual
doc/ directories, we could add UNIX-like paths:
bin/for executable commands (binaries and scripts)
lib/for shared libraries, such as shared functions for scripts
share/for architecture-independent shared data, such as images
etc/for local configuration
var/for anything that changes
var/lib/for data that persists over multiple executions
var/run/for runtime data like PID files
var/log/for log files
var/tmp/for temporary files and cache
opt/for self-contained directory hierarchies, such as Git submodules or embedded dependencies
This structure has some interesting and potentially useful consequences for how repositories are structured. Everything except
var/ should be tracked by version control, and everything in
var/ should be excluded from version control.
var/ is the only non-version-controlled directory, it is effectively the only “writable” destination for compilation. This means the files in
lib/ might be merely symlinks or scripts that point to generated files in
In a cloud or container environment,
var/ or its subdirectories could be mounted from a separate filesystem.
etc/ directory is tricky since a project may require temporary configuration files during development that should not be checked in. My thinking is that
etc/ should be restricted to things that are normally “checked in” like default configuration values. Local-only config should be under
var/. It’s not unheard of for *nix systems to have a
var/etc/, so that could work.
Of course, there is no universal standard for *nix filesystems, and no universal agreement on how to implement the standards we have. But as with a lot of things in software, you could do worse than to follow in the footsteps of UNIX.