i-dotfiles

An opinionated dotfiles organization scheme based on stow.

• Supports BASH (now legacy for me) and zsh.

• Supports Linux: x86 or amd64 or armhf or arm64.

• Supports macOS, both Intel and Apple Silicon.

• Includes configs for emacs emacs.d and zsh zprezto (managed as git submodule repos).

• Includes platform detection

Install

General Idea

Assumes git and GNU stow are available/already installed (usually via a package manager). Refer to specific "Starting point" README.md files below for specific details.

In general, it will go as follows:

1. Clone this repository:

   git clone --recurse-submodules \
     https://github.com/idcrook/i-dotfiles.git \
     ~/.dotfiles
   cd ~/.dotfiles

2. Install config for stow itself

   stow -t ~ stow

   IMPORTANT: Confirm the hard-coded home directory path in ~/.stowrc matches your system

3. Use stow to install desired package(s) via stow <directory> ¹

   • Additional installation instructions are present in respective platform and package README.md.

Starting Point

• macOS (Both Intel and Apple Silicon)
• Linux variants including Raspberry Pi OS (based on Debian) and Ubuntu flavors WSL2 or Ubuntu on Raspberry Pi

Rules

Sub-Directory Naming

• lowercase - for packages to stow install in $HOME (the default)

• leading _ - for non-stow-able packages, e.g. _pip which describes python package installation

• TitleCase - for packages which need root permissions, e.g. top-level of filesysyem at / @Apt

• leading @ - for environment packages and subpackages, e.g. @macos

Having a convention for sub-package naming enables a .stow-global-ignore file such that sub-packages are not symlinked when stowing parent package.

Ignore files

Quoting stow documentation :

if Stow can create a single symlink that points to an entire subtree within the package tree, it will choose to do that rather than create a directory in the target tree and populate it with symlinks.

Because of this, using .gitignore in packages (which do not themselves get stow-ed, due to stow-global-ignore) can help avoid this i-dotfiles git repository getting cluttered with unknown files. For example, this happens when language package managers add files to certain directories.

Secrets files

Secrets files, i.e., files that should not be committed to git repository, must have *.secrets* or */secrets/* in their filepath to be ignored by the root .gitignore file.

Each secrets file should be accompanied by an *.example* file that is, itself, instead commited to repository, to illustrate its contents by example.

Keep your secrets files as short as possible to limit their influence as it complicates deployments (as they will not be available in i-dotfiles git repository).

See example.

Background

I used to manage my macOS/Linux/WSL dotfiles in an "homedir.git" repository that was directly overlayed. This left things to be desired, and syncing multiple platforms sometimes presented unresolvable conflicts. Now, I use GNU Stow and this repository instead.

i-dotfiles is an opinionated dotfiles organization scheme based on stow. Its priorities are ease-of-maintenance and deployment on both Linux and macOS. It was created originally as an implementation of F-dotfiles, borrowing its philosophy as follows:

• stow powered: symlink dotfiles and thus keep them always up-to-date in git repository
• topical organization: organize dotfiles by application
• naming schemas: the repository architecture is easy to browse while staying compatible with stow symlinking mechanism
• documentation: each "package" directory has a README.md which presents its purpose. Install notes and requirements can be included. A separate TODO.md may be enlisted to track things still to be implemented.

Inspired heavily by:

• https://github.com/Kraymer/F-dotfiles
• https://github.com/andschwa/dotfiles
• http://dotfiles.github.io

---

1 it's because we installed stow package at step 2 that the flag -t ~ can be omitted here, see .stowrc ⤸