A JSON-configurable Git alias wrapper

Intro

The idea came from noticing a pattern in my own workflow: a small set of git commands covers the majority of my daily usage.
Put in Pareto terms, roughly 20% of the commands I know were doing 80% of the work, worth cutting down the effort rather than living with the repetition.
So I decided to build a simpler alternative to Git aliases. This post walks through gitwrap, a small Python wrapper that reads aliases from a JSON file, installed as a shell command using just a single symlink.

Where to start: the alias config

Aliases live in gitwrap/gitw/aliases.json. Each one maps a name to a list of git arguments:

{
  "aliases": {
    "st": ["status"],
    "co": ["checkout"],
    "cm": ["commit", "-m"]
  }
}

Enter fullscreen mode Exit fullscreen mode

Extra words typed after the alias on the command line are appended before running git — so gitw co main runs git checkout main.

Anything not found in the aliases is passed straight through to git unchanged, so gitw is a superset of git, not a replacement for it.

Running multiple commands from one alias

An alias can also be a list of commands instead of a single one:

{
  "aliases": {
    "sync": [["fetch", "--all"], ["pull"]]
  }
}

Enter fullscreen mode Exit fullscreen mode

gitw sync runs git fetch --all, then git pull.

• Extra CLI arguments are appended only to the last command in the sequence — gitw sync origin main runs git fetch --all followed by git pull origin main.
• If any command fails, the rest of the sequence is skipped and gitw exits with that same code.

The wrapper script

The script itself is a single file, gitw/cli.py, with no dependencies beyond the standard library. Aliases live in a JSON file(s):

• gitw/aliases.json the file that is part of the project, containing the defaults.
• ~/.gitw/aliases.json a personal file in the reader's home directory, which includes customized commands.

The two aren't mutually exclusive: the personal file is layered on top of the defaults, so adding one alias never means losing the rest.

Installing it as a real shell command

The cli.py can be symlinked straight onto your PATH, no virtualenv, no pip install, no build step:

chmod +x gitw/cli.py
mkdir -p ~/.local/bin
ln -sf "$(pwd)/gitw/cli.py" ~/.local/bin/gitw

Enter fullscreen mode Exit fullscreen mode

Add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Enter fullscreen mode Exit fullscreen mode

Verifying it works

gitw --help

Enter fullscreen mode Exit fullscreen mode

Running the alias list with --help shows exactly what each alias command does (single commands as git ..., chained ones as git ... && git ...).

Conclusion

If any of this is useful to you, the full source is available in Gitlab: gitwrap.
Feel free to add or rename the aliases to fit your own workflow.
Happy committing!