Comprehesive and portable environment configuration in a single file.
The goal of this script to safely(1) and predictably(2) store and update CLI and other app configurations from a single source, without using symlinks, Git or other more complex tools.
A single source ~/.shellrc should configure the shell environment and any supported (and installed) tools.
(1) Safely:
Configuration values coming from .shellrc are either appended or prepended to existing config files, in such a way that pre-existing user settings are preserved.
.shellrc's main() runs only under interactive shells and with set -euf for additional safety. These values are restored to set +euf on success.
(2) Predictably:
Configurations are only written for the tools that are already present in the system to minimise clobbering the ~/ and ~/.config dirs.
curl -fsSL https://raw.githubusercontent.com/tmslnz/shellrc/main/shellrc -o ~/.shellrc
. ~/.shellrc
.shellrc automatically checks for updates.
The last snapshot can be restored using:
shellrc revert
Updates can be manually requested using:
shellrc update
The updater saves previous versions in ~/.config/shellrc/snapshots
All code in the script is wrapped in funsctions.
There are two classes of functions in the script:
_shellrc_*: persistent in the session. These are utilities called throughout the script.configure_*: called once, thenunset -fto remove them from the symbols list.
The execution flow is controlled in main().
The script writes all configurations conditionally (i.e: x in PATH, OS == Darwin) and only within "fenced" sections (e.g. BEGIN_SHELLRC [...] END_SHELLRC).
Local changes outside of a fenced section are never over-written.
Fenced sections are stamped with a content-hash revision marker of ~/.shellrc; a section is only rewritten when that hash changes. Local changes within a fenced section are therefore eventually overwritten by an update.
Bash and Zsh are the primary targets. Plain POSIX sh (e.g. dash) is supported on a best-effort basis:
- The whole file must parse under
sh(check withdash -n shellrc; on macOSshis Bash and misses these errors). Shell-specific syntax such as arrays may only appear inside strings, heredocs oreval, or be replaced with a plain command (e.g.add-zsh-hook). - The file must source under
shwithout errors. - Features may be reduced or missing under
sh. Bash- or Zsh-only behaviour sits behind_shellrc_is_bash/_shellrc_is_zshand needs noshequivalent.
https://www.gnu.org/software/bash/
https://github.com/scop/bash-completion
https://en.wikipedia.org/wiki/Grep
https://www.gnu.org/software/emacs/
https://www.gnu.org/software/wget/
https://github.com/junegunn/fzf
https://github.com/ajeetdsouza/zoxide
https://github.com/pyenv/pyenv
https://kislyuk.github.io/argcomplete/
https://sourceforge.net/projects/automysqlbackup/
https://github.com/ko1nksm/shdotenv
Deletes directories fast, by syncing an empty directory over each one with rsync and then removing it. A symlink to a directory loses the link only; the target stays untouched. Refuses /, the current directory and its parents. Exits non-zero when any argument fails.
make # lint + test
make lint # dash/bash/zsh -n, shellcheck
make test # sh tests/run.sh
tests/run.sh is plain sh with no framework. It runs every test_* function under each installed shell out of dash, bash and zsh, each in a throwaway $HOME, so the real home directory stays untouched. Pass shell names to limit the run: sh tests/run.sh bash.
The last test sources the file in an interactive shell and runs main() twice. It exercises the configure_* functions of whichever tools are installed, and checks that the second run leaves the fenced sections unchanged.