Aliases — what they are, what they cost, and which ones to keep

A Git alias is a config key whose name starts with alias. and whose value is a string Git expands and prepends to the command line before execution. After git config alias.co checkout, the command git co main is functionally identical to git checkout main. The alias is a textual substitution, not a function: Git parses the expanded string as if the user had typed it. This is the source of both the speed and the brittleness.

Defining an alias

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate --all"
git config --global alias.unstage "reset HEAD --"

The first three are simple replacements. The fourth is a multi- flag command; the string is stored verbatim and Git splits it on whitespace before passing the pieces as the command and its arguments. The fifth shows the common “alias as verb” pattern: a single command that captures a workflow the engineer does often, here “unstage a file that was git added by mistake”.

After defining these, the following are all valid:

git co main
git br -a
git st
git lg -n 20
git unstage path/to/file

Any arguments the engineer types after the alias are appended to the expanded command, so git lg -n 20 becomes git log --oneline --graph --decorate --all -n 20.

flowchart LR
    A["alias.lg = log --oneline --graph --decorate --all"] --> B["git lg -n 20"]
    B --> C["git log --oneline --graph --decorate --all -n 20"]

Aliases worth keeping

A small set of aliases captures most of the productivity gain. The list below is the set the production engineers on the RunBook team have converged on; it errs on the side of well-known flags that are unlikely to change across Git versions:

• st -> status for the command that runs ten times a day.
• co -> checkout and br -> branch for the two commands that dominate branch work.
• ci -> commit for the common case; the flag-specific flags (-a, --amend, -s) still get typed explicitly.
• lg -> log --oneline --graph --decorate --all for a one- line graph that shows every branch. The four flags are old and stable; this alias rarely breaks.
• unstage -> reset HEAD -- for the recurring mistake.
• last -> log -1 HEAD for “what did I just commit”.
• diffc -> diff --cached for “what is staged right now”.

Aliases that wrap flags Git may change (--first-parent was introduced in 1.6.4, --graph formatting options have evolved across versions) are aliases that need maintenance when the Git binary is upgraded.

The maintenance cost

An alias is a string stored in a config file. The string is expanded by Git every time the alias is invoked, and the expanded command is parsed using the flags Git recognises in the running version. Three predictable failure modes:

1. Flags that change meaning. --decorate used to mean --decorate=short in older versions and accepts values like full, short, no in newer ones. An alias that pins --decorate to one value will not break, but an alias that wraps --format=%d may render differently across versions.
2. Flags that are removed. Git occasionally renames or removes flags. An alias that uses a removed flag is an alias that fails with error: unknown option.
3. Aliases that depend on shell features. An alias that uses ! to invoke a shell command (e.g. alias.visual = "!gitk") is portable only if the target binary exists on every machine the engineer runs the alias on. gitk is not installed by default on most server distributions.

The cost is paid by the engineer who maintains the alias, the engineer who upgrades Git and finds the alias broken, and the engineer who reads a teammate’s command (git lg) and has to reconstruct what flags it expands to.

Where aliases should live

The scope decision is the same as for identity:

• --global for personal aliases (st, co, br, lg). These follow the engineer across every repository.
• --local for aliases that only make sense in a specific repository. Examples are aliases that wrap the repository’s CI command (alias.ci-test = test for a project whose test target is a long, project-specific command) or aliases that invoke repo-specific tooling.
• Shared via includeIf.gitdir: for team-wide aliases. The pattern is: keep the aliases in a file in a dotfiles repository, and pull them in conditionally per repository.

Production discipline

1. Keep the alias set small and stable. Five to ten aliases that every engineer knows cover the productivity gain. A hundred aliases that only one engineer knows cover the same ground with a maintenance cost the team will not pay.
2. Pin aliases to old, stable flags. --oneline, --graph, --decorate, --cached, -1 are stable; the newer --format options and the experimental output flags are not.
3. Avoid shell-out aliases (alias.x = "!command") in shared alias files. They depend on binaries that may not be installed on every machine and produce errors that look like Git errors.
4. Version-control shared aliases. Put them in a file in a dotfiles repository or in the team’s gitconfig-shared and pull them in via includeIf.
5. Document non-trivial aliases. An alias that wraps a long command is one the engineer who reads the output will need to decode. A short comment in the shared config file is enough.

Quiz