These are my dotfiles managed with GNU Stow. Use in conjunction with ansible-workstations for a complete setup.

• GNU Make
• GNU Stow
  • Online manual
  • Example usage
• direnv (optional, for development)
  • Online documentation

make list         # List packages
.bin/listdeps     # List packages and their external dependencies

make configure    # Decide which packages you want
make [PACKAGE]... # Install specified packages and packages on which they depend

make dist         # Generate a new example-local.mk from package directories

Each package can have a top-level README.* file which will not get stowed. This is due to Stow’s builtin ignore list, as defined in the Stow manual.

When directories are folded (symlinked back to Stow), files installed into those directories by other processes on the system physically live in Stow, which is the wrong place for them.

The main downside to not folding directories is that when they are unstowed, the target directories are not removed even if they are empty. This doesn’t hurt anything, though, unless the filesystem is running out of inodes.

Considering the above two points, the GNUmakefile disables directory folding by default. In the odd case where a package requires directory folding (e.g. the doom package), its GNUmakefile rule should contain a target-specific variable assignment to STOWFLAGS to remove the --no-folding flag.

In my opinion, configuring packages to conform with the XDG Base Directory specification provides little to no value when managing dotfiles with Stow. I am currently migrating away from XDG Base Directory compliance for the following reasons:

1. It introduces significant boilerplate in config files, reducing signal-to-noise ratio and increasing shell startup time.
2. It complicates the Stow directory structure, adding extra path components with duplicate organizational semantics (e.g. zsh/.config/zsh/ vs. zsh/)
3. The XDG Base Directory specification is often misunderstood and abused by programs (e.g. caching runtime data in $XDG_CONFIG_HOME); why migrate from one imperfect system to another?

Dotfiles and data for each package are organized according to the XDG Base Directory specification where feasible. When a program does not follow XDG conventions by default, one of the following techniques is applied to bring it into compliance (listed in preferred order):

1. Environment variable(s) in .profile.d/
2. Wrapper alias in .environ.d/

Dotfiles can be managed in many different ways. Here are a few approaches:

1. Have a git repo in $HOME
2. Generate dotfiles from templates and copy into place
3. Symlink into place (this repo)

• Portability
  • Dependencies
• Configurability
  • Templates
  • Includes
• Maintainability
  • Simplicity
  • Modularity

I believe that the GNU Stow approach strikes the best balance:

• Very light and portable dependencies
• No templates, but includes work for most dotfiles
• Easily the most maintainable