for the past year i have kept a public dotfiles repository. every script, alias, and configuration file lives under version control. some of these tools became essential. most did not. this is the retrospective.
the survivors
three scripts survived the year without modification:
t — a directory jumping tool that maintains a stack of visited directories. it replaces cd for the common case of moving between a few deeply nested paths. the implementation is eight lines of bash. i use it about fifty times per day.
g — an interactive grep that pipes rg output into fzf and opens the selected match in $EDITOR. this is not an original idea, but packaging it as a single function in my .bashrc means it is always available, always the same, and never depends on an external plugin manager.
wttr — a weather report that fetches from wttr.in and renders it in the terminal. the commit history shows the original request went in on a rainy monday morning and has been untouched since.
a fourth, buku integration, deserves mention: a shell function that opens any bookmark from my browser’s bookmark store directly in the terminal using a curses-style picker. this replaced a browser plugin that had been silently exfiltrating my browsing data for three years.
the casualties
the scripts that did not survive fell into two categories. the first was scripts that solved a problem once and never needed to run again — migration helpers, one-time data transforms, setup scripts for a now-defunct server. these lived in a separate archive/ directory before i deleted them.
the second category was scripts that tried to do too much. a backup script that handled compression, encryption, upload to three destinations, and error notification. it had a config file, a dry-run mode, and a test suite. it broke every time i changed operating systems. the replacement is a three-line wrapper around rsync that only handles the local copy; the rest is handled by system-level tools.
what i learned
a small sharp tool has three properties:
- it does one thing
- it does it without asking questions (no interactive prompts)
- the output is valid input to another tool
the third property is the one most dotfile projects get wrong. if your script prints a formatted table that cannot be grepped, it is not a tool — it is a widget. a real tool produces output that composes. a real tool fails with a non-zero exit code and a message on stderr, not a dialog box.
conclusion
maintaining dotfiles is gardening. you plant scripts, some grow into habits, most die. the trick is recognizing which is which before you invest in a readme, a man page, and a --help flag.