i-dotfiles is an opiniated dotfiles organization scheme based on stow. (Implementation of F-dotfiles) Highest priorities are ease of maintenance and deployment on both Linux and macOS.
stowpowered: symlink dotfiles and thus keep them always up-to-date in your repository
- topical organization: organize dotfiles by application facilitating reuse across different machines
- clever naming scheme: the repository architecture is easy to browse while staying compatible with
- KISS: there is deliberately none build script involved at all, the repository consist of dotfiles all installable using same modus operandi (
- documentation: each package has a README.md which present its purpose and a flat
treeview of its files. Install notes and requirements can also be listed. a TODO.md is enlisted to track things to be done.
Inspired heavily by:
I used to manage my macOS/Linux/msys2/WSL dotfiles in a "homedir.git" repository. This left things to be desired, and syncing multiple platforms sometimes presented unresolvable conflicts. Now I use GNU Stow and this organization.
- Assumes GNU
- clone the repository :
git clone https://github.com/idcrook/i-dotfiles.git ~/.dotfiles ; cd ~/.dotfiles
stow, inception style :
stow -t ~ stow
- install desired package via
- lowercase for packages to install in
- titlecase for packages to install as root in
@for environment packages and subpackages, eg
_for non packages, eg
_pipmeaning that these directories must not be stowed
Having a convention for subpackage naming enable us to write a
.stow-global-ignore file so that subpackages are not symlinked when stowing parent package.
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.
.gitignore can be present in packages because of this behaviour, in order to avoid having your repository cluttered with unknown files
Secrets files, ie files that should not be commited/published, must have .secrets or /secrets/ in their filepath to be ignored by the root
Each secrets file should be accompanied by an *.example file that is commited instead, to illustrate the use.
Keep your secrets files as short as possible to limit their influence as it complicates deployments (as they cannot be just pulled from github).
Where to save a file that is installed at different locations depending on the OS ?
The trick is to have one package per OS, just to create each specific directories structure properly.
Then create the part of the filepath that is common to the two OS in
<package>/_common, put the files in it, symlink from the subpackages to that location.
Feel confused ? Check example