3 March 2021

On The CLI Design of Git

I’m sorry. I know people like Git. I know it’s the de facto standard VCS for the industry. But the command line UI of Git is awful. There’s no consistency to anything.

Here’s an example. How do you list the following: tags, stashes, and remote services? Before you read on, have a go at guessing. See if you can do it on the first try without looking at the help.

Ok, here are the answers: for tags, it’s git tag, or git tag -l. For stashes, it’s git stash list. For remotes, it’s git remote -v.

Notice that each usage for listing something is different. There is nothing I can mentally grasp onto as the way to list the particular thing that I want to operate on. What would have been better is that each one responded to something like --list, even if the default would have produce the listing as well. That way, if I’m unsure that simply running git tag or git stash will produce a listing, I can simply fall back to running git something --list. Because this is lacking, I’m constantly using --help or -? to get the command usage, or accidentally creating new stashes because I expect that listing them is the default usage of the command, just like git tag.

Which brings me to the second example: type git remote -? and get a list of all the subcommands, showing usage patterns for adding, removing or modifying remote services. Type git stash -? and you get the switches that are only used by git stash. There is nothing to suggest that there are any subcommands, which is difficult to believe as none of the switches can be use to list or remove stashes (no, -v doesn’t do it, in fact, -v doesn’t do anything for that command: you just get the usage message). Again, consistency is needed here. Either list all the subcommands when the -? is used, or only the switches for that particular command. I don’t care which way you choose, but pick one, and use it across all the commands you offer.

The actual source revision side of Git is pretty good, and offers so much over the alternatives like Mercurial. I just wish the CLI showed the same level of care.


Previous post
🔗 Blueutil: Bluetooth CLI tool for MacOS 🔗 Blueutil A CLI tool for controlling Bluetooth for MacOS. Might be useful for an idea I have whereby I turn off Bluetooth at a certain time of
Next post
Random Thought Update 4/3 I’ve been using Random Thought, the little MacOS app I hacked together for writing on this blog, for a little while now. For a time, I’ve been