F-dotfiles

/ɛfdɒtfaɪlz/ :

n. stands for Full-fledged-Über-Clean-Kraymer dotfiles., an opiniated dotfiles organization scheme based on stow. Great effort is put on self-documentation and ease of maintenance.

Features

• stow powered: symlink dotfiles and thus keep them always up-to-date in your repository
• topical organization: organize dotfiles by application packages facilitating reuse across different machines
• discoverability: self-documented packages making the architecture easy to browse while staying compatible with stow symlinking mechanism

Install

1. clone the repository : git clone https://github.com/F-dotfiles/F-dotfiles.git ~/ ; cd ~/F-dotfiles
2. setup stow, inception style : stow -t ~ _stow 
3. install desired package via stow <directory> ¹

When needed, special install instructions are present in package README.md file

Rules

Walter - That rules really tie the repo together, do they not?
The Dude - Fuckin A ! ²

Documentation ^{_{f-dotfiles.py}}

Dotfiles repositories are too often grimoire-like collection of ancient formulas, only usable by their original author.

F-dotfiles avoid this pitfall by paying special attention to packages documentation : run pre-commit install to enable f-dotfiles.py hook that ensures that packages README.md tree listings are automatically updated when commiting.
Files descriptions that match the format # <filename>: description are extracted too and enrich the tree listing.

Others instructions like install notes and requirements should be manually entered by editing the README.md files directly, and can live peacefully alongside auto-generated tree view content.

Ignore files ^{_{[cf example]}}

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.

Secret files ^{_{[cf example]}}

Files that contain sensitive information and should not be published are kept secret using package specific .gitignore files. Because the secret file itself is not tracked, a template is commited instead having same name but with the .example suffix appended. This template is intended to serve as a base for edition and can be renamed (removing the suffix) after its content is edited.

1 it's because we installed stow package at step 2 that the flag -t ~ can be omitted here, see .stowrc ⤸
2 https://www.youtube.com/watch?v=ezQLP1dj_t8 ⤸