Git-Config: alias.*
Using Aliases to Shorten Commands—And Correct Your Own Typos
Git has built-in support for aliases, which are custom commands that you can define. Once defined, you can run your alias just like any other Git command that follows the invocation of git
on the command line.
If you’ve been working alongside the posts in this series, your Git configuration has probably been getting lengthier. To see a list of all of your global configuration values, you probably know to run this command:
$ git config --global --list
user.name=Darth Vader
user.email=vader@deathstar.example.com
pull.rebase=false
init.defaultbranch=main
core.pager=less -FX
core.whitespace=-space-before-tab,tab-in-indent
core.editor=nova --wait
diff.colormoved=zebra
diff.colormovedws=allow-indentation-change
I use that command frequently enough that I alias it to cgl
(config global list) in my global config. If you’ve never created a Git alias before, you can set them in your configuration file with alias.<ALIAS_NAME>
. To alias the command above, we’ll use alias.cgl
.
To create a basic alias, you need only to reference any valid commands and options that normally follow the git
command:
$ git config --global alias.cgl "config --global --list"
$ git cgl
user.name=Darth Vader
user.email=vader@deathstar.example.com
# ...other output omitted...
As you can see in that example, Git commands (such as config
) as well as any of the command’s arguments (--global
, --list
) are permissible in any alias you write.
Checking That Your Alias Is Safe To Use
Note that Git will ignore any aliases that conflict with its own built-in commands. You cannot, for example, write your own alias for log
. Rather than finding out the hard, head-scratching way that Git already has a command that your alias conflicts with, just test out your candidate alias with Git and append the --help
option so you don’t accidentally execute something:
$ git who --help
git: 'who' is not a git command. See 'git --help'.
In that event, who
would be a safe choice for an alias: it’s not a Git command.
Preventing the Invocation of Git
In fact, who
is a great alias if you are checking to see who you are—your name and email address—in a given repository, especially if you’re in the habit of using a different name or email address on certain projects. Here we’ll use git config --get
twice, each time with the key whose value we want to retrieve.
$ git config --global alias.who "\!git config --get user.name && git config --get user.email"
Note the exclamation mark, or bang (!
) , near the start of that alias. The bang short-circuits Git’s usual assumption that the alias itself invokes the git
command. (Using the bang, you can actually write Git aliases for any shell command you like.) But because who
calls git
a second time, to output the user.email
value, it’s necessary to use the bang the first time around and manually call git config
both for the current name and email.
Note also that the bang is escaped with a backslash: \!
. That is to prevent the history-expansion behavior common inside double quotes in many shells.
The end result is pretty great, though, especially if you change identities across different projects:
$ git who
Darth Vader
vader@deathstar.example.com
Aliasing Your Typos
Beyond supporting shortened forms of useful commands, aliases provide aid and comfort to those of us who are naturally sloppy on the keyboard. For example, that second F in diff
is just a colossal inconvenience to type, or so my lefthand index-finger believes. Aliases to the rescue:
$ git config --global alias.dif "diff"
Now I can type git dif
and Git will know exactly what my intention is.
Aliasing Shortcuts to Common Commands
Then there are frequently used commands whose full names are either just needlessly long or tricky to type accurately, like git status
:
$ git config --global alias.s "status"
With that alias set, git s
is all you need to get the status of your repo.
But frankly even the space between git
and s
makes me feel like I’m working way too hard. If you feel the same way, you can go even further and write an alias at the level of your command-line shell’s configuration file—~/.zshrc
in my case. Let’s make a shell alias that references the s
Git alias:
# in ~/.zshrc
alias gits="git s"
Using your shell to alias your Git aliases can be smart, should you decide to change any arguments passed in as part of your shortcut Git-aliases in the future. That ensures that your shell alias effectively auto-updates to the values you alias in Git itself.
⚠ Remember to run source ~/.zshrc
(or whatever the filename is for your shell’s config file) so your changes take effect in your active terminal session.
Passing Additional Arguments to Git Aliases
One of the many convenient things about aliases, beyond their ability to save you keystrokes, is that you can append them with additional arguments and options. That’s true whether you’re using a Git alias or an alias from your shell:
$ git s --short
M readme.md
The next post in this series will look at configuration values for git status
. There are a surprising number of them. And we’ll also reason more thoughtfully about how to best express your preferences to Git: as a configuration value, an alias, or a good old-fashioned argument from the command line.
Karl’s book, Programming WebRTC: Build Real-Time Streaming Applications for the Web, is available in beta from The Pragmatic Bookshelf. You can save 35 percent with promo code git_config_2022 now through October 31, 2022. Promo codes are not valid on prior purchases.