Git Aliases: Faster, Clearer Git Commands

A Git alias is a configuration entry that expands to another command. git st runs git status; git lg runs whatever twelve-flag log invocation you actually want.

Aliases are stored in Git configuration, so they are not shell aliases and they work regardless of which shell you use. They are the cheapest productivity improvement in this cluster, and the easiest to overdo.

Before you start

• Git Configuration for scopes and precedence, though this lesson stands alone.

Creating one

git config --global alias.st status

What it doesWrites an alias.st entry into your global Git configuration, so git st becomes shorthand for git status.

Why we run itAliases live in Git config rather than your shell, so they work identically in bash, zsh, PowerShell and any tool that shells out to Git.

Expected resultNo output. git st now behaves exactly as git status would.

Aliases with arguments work the same way — quote the whole value:

git config --global alias.lg "log --oneline --graph --decorate -20"

git lg

* 2588332 (HEAD -> main) api change 5
* 3b0d2f7 api change 4
* b146290 api change 3

Any arguments you pass are appended, so git lg --author=alice works as expected.

Where they live

Aliases are ordinary configuration, which means the usual scopes apply:

Scope	Command	File	Applies to
Global	--global	~/.gitconfig	All your repositories
Local	--local	.git/config	One repository
System	--system	/etc/gitconfig	Everyone on the machine

Global is almost always right. A local alias is occasionally useful for a project-specific command, but remember that it is not shared — .git/config is not committed.

Editing the file directly is often easier than repeated git config calls:

[alias]
    st = status --short --branch
    lg = log --oneline --graph --decorate -20
    last = log -1 --stat

Simple aliases

An alias whose value does not begin with ! is a Git subcommand plus arguments. Git prepends git and appends whatever you typed.

[alias]
    co = checkout
    sw = switch
    br = branch
    st = status --short --branch
    ci = commit
    unstage = restore --staged
    last = log -1 --stat
    amend = commit --amend --no-edit

These are safe, portable and readable. If you only ever create simple aliases, you will get most of the benefit with none of the pitfalls.

Shell aliases

Prefix the value with ! and Git runs it through the shell instead:

git config --global alias.root '!pwd'
git root

/home/you/project

This unlocks anything a shell can do — pipes, multiple commands, other programs — with two important caveats.

Positional arguments need a function

A common surprise: shell aliases append arguments rather than substituting them.

git config --global alias.bad '!git log --since=$1'
git bad "1 week ago"

$1 is empty, and "1 week ago" is appended to the end of the command. The usual fix is to define and immediately call a shell function:

git config --global alias.since '!f() { git log --oneline --since="$1"; }; f'
git since "1 year ago"

2588332 api change 5
3b0d2f7 api change 4

The trailing ; f calls the function; without it, nothing runs. Arguments are still appended after f, which is exactly what makes "$1" work.

They run from the repository root

A shell alias executes from the top level of the working tree, not from your current directory. That is usually convenient and occasionally surprising if you expected a relative path to resolve where you stood.

Quoting is the hard part

Shell aliases pass through two levels of quoting: the shell you type in, and the shell Git invokes. The usual approach is single quotes around the whole alias, double quotes inside:

git config --global alias.example '!f() { echo "$1"; }; f'

If an alias behaves strangely, look at what was actually stored:

git config --get alias.example

Editing ~/.gitconfig directly avoids one layer of shell quoting entirely, and is often less painful for anything complex.

A curated set

These are chosen to be useful and to remain comprehensible to someone reading over your shoulder.

Status and inspection

[alias]
    st = status --short --branch
    last = log -1 --stat
    lg = log --oneline --graph --decorate -20
    graph = log --oneline --graph --decorate --all
    who = shortlog --summary --numbered --no-merges

Staging and committing

[alias]
    unstage = restore --staged
    amend = commit --amend --no-edit
    wip = commit --no-verify -m "wip"

Branches

[alias]
    branches = branch --sort=-committerdate --format='%(committerdate:relative)%09%(refname:short)'
    merged = branch --merged
    unmerged = branch --no-merged

branches is the one people keep — it lists branches newest first with their age, which is exactly the view you want when deciding what to delete:

3 minutes ago  main
2 days ago  feature/search-ranking
5 weeks ago  spike/new-parser

Reviewing your own work

[alias]
    review = "!f() { git diff \"${1:-main}...HEAD\"; }; f"
    incoming = "!f() { git log --oneline \"HEAD..${1:-origin/main}\"; }; f"
    outgoing = "!f() { git log --oneline \"${1:-origin/main}..HEAD\"; }; f"

review uses the three-dot form, comparing against the merge base rather than the branch tip — which is what you want when reading your own branch. Git Branches Explained covers why.

Recovery

[alias]
    undo = reset --soft HEAD~1
    rl = reflog --date=relative

undo removes the last commit while keeping every change staged — the safe form. It deliberately does not use --hard.

Name aliases for what they do

git undo is memorable. git rs1 is not, and neither is git ff. The point of an alias is to make a command easier to recall, so an alias you have to look up has failed.

A useful test: could a colleague guess what it does from the name? If not, either rename it or accept it is a private shortcut you will not be able to explain.

Dangerous aliases

Some aliases make destructive operations too easy.

# Do not do this
[alias]
    nuke = reset --hard
    f = push --force
    cleanup = "!git reset --hard && git clean -fdx"

The problem is not that these commands exist — it is that shortening them removes the pause that made you think. git push --force is long enough to prompt a moment’s consideration; git f is not.

Never alias a force push to something short

If you must have one, make it the safe variant and keep the name deliberate:

[alias]
    push-force-safely = push --force-with-lease --force-if-includes

Long, unambiguous, and it will not be typed by accident. When Not to Rebase explains why bare --force deserves the friction.

Similarly, avoid aliasing anything that combines reset --hard with clean -fdx. That pair deletes uncommitted changes and untracked files including ignored ones — configuration, environment files, build caches. It is occasionally what you want, and it should always be typed out.

Aliases cannot shadow built-in commands

git config --global alias.status "log -1"
git status --short

?? .githooks/

The built-in wins. Git resolves real commands before aliases, so you cannot accidentally break status, commit or push.

This is a safety feature. It also means an alias that appears not to work may be colliding with a subcommand you did not realise existed — check with git help -a.

Inspecting and removing

List them:

git config --global --get-regexp '^alias\.'

alias.st status
alias.lg log --oneline --graph --decorate -5
alias.root !pwd
alias.since !f() { git log --oneline --since="$1"; }; f

See what one expands to:

git config --get alias.lg

log --oneline --graph --decorate -5

Remove one:

git config --global --unset alias.st

Find out where an alias came from, when the same name exists in several scopes:

git config --show-scope --show-origin --get alias.st

Team portability

Aliases are personal configuration and are not shared by cloning. That is mostly a good thing — people have different preferences — but it has consequences worth planning for.

Documentation should use real commands. A README saying “run git lg” is useless to anyone without your config. Write the full command.

Scripts must not use aliases. A CI job or shell script invoking git st breaks on any machine where that alias does not exist. Always spell commands out in automation.

Shared aliases need a setup step. A project that genuinely wants shared aliases can commit a config file and have people include it:

git config --local include.path ../.gitaliases

The path is relative to .git/, so ../.gitaliases refers to a file at the repository root. That file can contain an [alias] section like any other config. The include.path line itself still has to be run per clone.

Aliases versus shell functions

An alias cannot change your shell’s working directory, because it runs in a subprocess. Anything that needs to cd — such as creating a worktree and moving into it — has to be a shell function in your dotfiles instead:

wt() { git worktree add "../$1" "${2:-$1}" && cd "../$1"; }

Use Git aliases for Git operations, and shell functions when you need to affect the shell itself.

Aliases that call other aliases

An alias can invoke another, because expansion happens at run time:

[alias]
    lg = log --oneline --graph --decorate -20
    lga = "!git lg --all"

Note that lga must be a shell alias. A simple alias expands to a Git subcommand, and lg is not one — Git resolves built-in commands and then aliases, but a simple alias’s first word must be a real command. Prefixing with ! sidesteps this by going through the shell, where git lg resolves normally.

This works and is occasionally useful. It also makes debugging harder: a broken alias three levels deep produces an error mentioning none of the names you typed. Keep chains to one level.

Useful patterns worth stealing

A few aliases that solve real problems rather than just shortening commands.

Fixup the commit that last touched a file — the tedious part of the autosquash workflow is finding the target commit:

[alias]
    fixup = "!f() { git commit --fixup=\"$(git log -n1 --format=%h -- \"$1\")\"; }; f"

git fixup src/parser.py creates a fixup commit targeting whichever commit last modified that file.

Show what a branch adds, against the merge base:

[alias]
    what = "!f() { git log --oneline \"${1:-main}..HEAD\"; }; f"

Find deleted files in history, which is otherwise an awkward invocation:

[alias]
    deleted = "!f() { git log --diff-filter=D --name-only --format='%h %s'; }; f"

Open the repository’s default branch:

[alias]
    main = "!git switch \"$(git symbolic-ref --short refs/remotes/origin/HEAD | sed 's|origin/||')\""

Useful on teams where some repositories use main and others master.

Build the collection gradually

The aliases that stick are the ones you wrote because you were annoyed by typing something for the fifth time that day. Copying a list of sixty from an article produces a configuration file you do not know.

Start with three or four. Add one when a command irritates you. Delete any you have not used in a month.

Common mistakes

Expecting $1 to work without a function. Shell aliases append arguments. Wrap in f() { … }; f.

Forgetting the trailing ; f. The function is defined and never called, so nothing happens.

Aliasing destructive commands to short names. Removes the friction that prevents accidents.

Using aliases in scripts or documentation. They do not exist on other machines.

Cryptic names. An alias you cannot remember is worse than the command it replaced.

Trying to override a built-in. Git resolves real commands first.

Quoting errors. Check with git config --get alias.<name>; edit ~/.gitconfig directly for anything complex.

Building an enormous collection. Ten aliases you use daily beat sixty you half-remember.

Mental Model

An alias is a shorter name for something you already do.

It does not add capability, and it should not add risk. The best ones replace a command you type several times a day with something you can type without thinking; the worst ones make a dangerous command easy to type without thinking.

What You Learned

• Aliases live in Git configuration, so they work in any shell and any tool that invokes Git.
• A value not starting with ! is a Git subcommand; ! runs it through the shell.
• Arguments are appended, not substituted — positional arguments need f() { … }; f.
• Aliases cannot override built-in commands.
• git config --get-regexp '^alias\.' lists them; --show-origin finds where one came from.
• They are personal configuration and are not cloned; never use them in scripts or documentation.
• Anything needing to change directory must be a shell function, not a Git alias.
• Do not shorten destructive commands; the length is part of the safety.

Try It Yourself

1. Create a simple alias and use it:

   git config --global alias.st "status --short --branch"
   git st

2. One with arguments:

   git config --global alias.lg "log --oneline --graph --decorate -10"
   git lg
   git lg --author="$(git config user.name)"

   Note that your extra argument was appended.

3. A shell alias:

   git config --global alias.root '!pwd'
   cd some/subdirectory && git root

   Predict: which directory does it print?

4. The positional-argument trap:

   git config --global alias.bad '!git log --oneline --since=$1'
   git bad "1 week ago"

   Observe that it does not do what you meant.

5. Fix it with a function:

   git config --global alias.since '!f() { git log --oneline --since="$1"; }; f'
   git since "1 week ago"

6. Try to shadow a built-in:

   git config --global alias.status "log -1"
   git status --short

   Predict the result.

7. Clean up:

   git config --global --unset alias.status
   git config --global --unset alias.bad
   git config --global --get-regexp '^alias\.'

Steps 4 and 6 are the two behaviours that surprise people: arguments append rather than substitute, and built-ins always win.

Next Lesson

Maintenance is the counterpart to ergonomics — keeping the repository itself fast as it grows.

Lesson 8 — Git MaintenanceRepacking, commit-graphs, scheduled maintenance, and when to leave Git alone.

Lesson 9 — Git ConfigurationThe full configuration reference, including scopes and precedence.