The Terrible UX of Git

Nov 19, 2021

New software developers of all kinds all struggle with the same tool: using git for version control.

Coworkers who had post-it notes to remind them of aliases or common operations. Others, finding themselves in a complex situation, deleting the entire repository and starting over again. Some sources of confusion:

  1. Overloaded commands like "checkout" - it can either switch a branch, create a new branch, or restore a file to a previous version.
  2. git ships with 137 top level commands. Including ones like send-email and instaweb.
  3. Keeping track of the working tree, index and staging area, local repository, and remote repository. Expert question: how does git store stashed changes?
  4. Multiple ways to do things like reconcile changes (rebase or merge) or restore a previous version of a file (checkout or restore).
  5. High time to value. Getting code and making a change requires understanding things like ssh keys, remotes, branches, and staging changes to name a few. Lots of concepts to master.

As someone who understands git internals (by trying to write my own version control system more than once), I still find myself referencing the documentation to do certain operations.

It's clear that these UX issues don't cause enough pain to drive users to a simpler tool. Even "easier" abstractions like Magit or GitHub Desktop have failed to reach mass adoption. But with the right approach, we could make it significantly easier to become a new software engineer.

See: xkcd 1597