Skip to content
loadout

What loadout is

loadout is a curated set of shell aliases, functions and workflows. You describe your git identity, your project directories and your machines in one configuration file. loadout renders the two together into a single file your shell sources at startup.

Configure your environment. Do not maintain a fork of it.

The problem it addresses

Section titled “The problem it addresses”

Dotfiles accumulate. They grow by accretion until nobody chose the result: an alias added in 2019 for a tool you uninstalled in 2021, a path that points at a directory two laptops ago, a function that works on Linux and silently does the wrong thing on macOS. The file is 800 lines and every line was once a good idea.

The usual fix is to fork someone else’s dotfiles repository. That trades one maintenance burden for another, because now their opinions and your particulars live in the same files, and every upstream change is a merge.

loadout separates the two:

  • The catalog is the product — 136 aliases and 14 shell functions, shipped and versioned, the same for everyone.
  • Your configuration is data — a YAML file naming your git identity, your project root, your workspaces, your hosts, your credential names.

loadout apply renders one against the other. Upgrading the catalog is brew upgrade and does not touch your configuration. Changing your particulars is an edit to one file and does not fork anything.

What that gets you

Section titled “What that gets you”

Your environment is reproducible. The same configuration on a new machine produces the same shell, minus whatever is not installed there — which loadout tells you about rather than failing at.

It is explainable. loadout describe pw tells you what a command does, how to call it, and what it needs. loadout doctor tells you what on this machine is not satisfied.

It is not another thing to maintain. The parts that would rot are generated. The part you own is data.

What it is not

Section titled “What it is not”

loadout is not a prompt theme, a plugin manager, or a first shell setup. It does not make your terminal prettier and it has no opinion about your prompt. If you do not already have an accumulated dotfiles problem you recognise, it is solving something you have not run into yet.

It also does not manage your shell configuration file. It writes one file and tells you the single line to add. That line is yours to add, and yours to remove.

A curated catalog asks you to trust someone’s judgement about what belongs in your shell. What loadout leaves out is that judgement written down: the rules an entry has to clear, and the entries that were dropped or renamed for failing them.

The constraint that shapes everything

Section titled “The constraint that shapes everything”

An alias cannot be a program. gpush and .. are shell state, not executables, so no binary can provide them — a compiled tool can only ever hand your shell some text and ask it to evaluate it.

loadout therefore generates shell rather than intercepting commands, and the binary stays out of the hot path. The generated file is static text, regenerated only when you run loadout apply. Nothing runs when you open a terminal, so loadout costs you no startup time at all.

Two shipped functions, p and activate, change the calling shell’s directory and environment. They stay real shell functions for the same reason: a child process cannot cd for its parent.

Where to go next

Section titled “Where to go next”