Skip to content
tmslnzPublic

About

Highly portable, single file POSIX shell configuration

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

94 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

~/.shellrc

Comprehesive and portable environment configuration in a single file.

Overview

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.

Install

curl -fsSL https://raw.githubusercontent.com/tmslnz/shellrc/main/shellrc -o ~/.shellrc
. ~/.shellrc

Update

.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

Conventions

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, then unset -f to 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.

Shell compatibility

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 with dash -n shellrc; on macOS sh is Bash and misses these errors). Shell-specific syntax such as arrays may only appear inside strings, heredocs or eval, or be replaced with a plain command (e.g. add-zsh-hook).
  • The file must source under sh without errors.
  • Features may be reduced or missing under sh. Bash- or Zsh-only behaviour sits behind _shellrc_is_bash / _shellrc_is_zsh and needs no sh equivalent.

Supported Tools

Bash

https://www.gnu.org/software/bash/

Bash Completion

https://github.com/scop/bash-completion

Z shell

https://www.zsh.org

ssh

https://github.com/sharkdp/fd

grep

https://en.wikipedia.org/wiki/Grep

Emacs

https://www.gnu.org/software/emacs/

Vim

https://www.vim.org/

Nano

https://www.nano-editor.org

NPM

https://www.npmjs.com

Git

https://git-scm.com

Wget

https://www.gnu.org/software/wget/

fd

https://github.com/sharkdp/fd

fzf

https://github.com/junegunn/fzf

Zoxide

https://github.com/ajeetdsouza/zoxide

Perlbrew

https://perlbrew.pl

SDKMAN!

https://sdkman.io

mise

https://mise.jdx.dev

pyenv

https://github.com/pyenv/pyenv

python

https://www.python.org

python argcomplete

https://kislyuk.github.io/argcomplete/

direnv

https://direnv.net

broot

https://dystroy.org/broot/

ncdu - NCurses Disk Usage

https://dev.yorhel.nl/ncdu

automysqlbackup

https://sourceforge.net/projects/automysqlbackup/

GoAccess

https://goaccess.io

Composer

https://getcomposer.org

shdotenv

https://github.com/ko1nksm/shdotenv

Utility Functions

get_user_home <username>

remove_host_key_at_line <line>

list_all_binaries

zap <dir>...

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.

git_lf <dir>

git_freeze_submodule <path>

configure_nebula

Development

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.

About

Highly portable, single file POSIX shell configuration

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages