New zine: How Git Works!

How Git Works: A New Zine for Long-Time Users Who Still Fear Git

Julia Evans has released How Git Works, a new zine aimed at developers who have used Git for years but still find it intimidating. It is available for $12 individually or as part of a 14-zine bundle.

What Problem Does It Solve?

Evans wrote the zine for people who remain uncomfortable with a tool they use daily. The goal is to build confidence by:

• Demystifying scary-sounding concepts like "detached HEAD state," which become straightforward once the underlying mechanics are clear.
• Flagging genuinely risky areas—such as the stash, where work can be lost in ways that are particularly painful to recover from.
• Correcting common misconceptions about core components like commits, branches, and merging.

The content intentionally focuses on Git's observed behavior rather than its internals. While the zine includes a couple of pages on the .git directory, the main emphasis is connecting what you see in Git's user interface to what is actually happening under the hood. For example, it's easy to find documentation saying that remote-tracking branches "remind you where the branches in your remote repositories were the last time you connected to them," but that doesn't make it obvious that a status message like Your branch is up to date with 'origin/main' doesn't necessarily mean you're current with the remote main branch.

Where Git Confuses Users

Writing the zine was challenging because Evans had used Git confidently for a decade and had lost touch with the initial learning curve. Through feedback from collaborators and the Git community on Mastodon, she identified several recurring sources of confusion:

• Terminology: Words like "fast-forward," "reference," and "remote-tracking branch" are not self-explanatory.
• Misleading messages: The "up to date" status message is a prime example.
• Uninformative output: Merge conflicts still do not clearly indicate which code came from which branch.
• Poor guidance on divergence: Running git pull after your branch has diverged from the origin doesn't help you decide what to do next.
• Inconsistent behavior: Reflogs are normally append-only, except for the stash, where git stash drop deletes entries.

These issues make Git's internal logic hard to reverse-engineer just by using it. However, once the meaning behind the error messages and warnings is understood, dealing with them becomes routine. An error like error: failed to push some refs to 'github.com:jvns/wizard-zines-site' likely means a coworker changed main, and a quick git pull --rebase resolves it. Likewise, a "detached HEAD" warning is no cause for alarm—just run git checkout mybranch before continuing to work.

What You Get

The zine includes a free printable cheat sheet, and an HTML transcript has been added to improve accessibility for screen readers. All pages were transcribed with image descriptions by the publisher's Operations Manager, Lee. Evans notes that print orders will not ship until July, as she needs to gauge demand before going to the printer.

How It Differs from "Oh Shit, Git!"

This is not Evans' first Git-related zine. Oh Shit, Git! is a collection of tricks for fixing Git mishaps, originally conceived by Katie Sylor Miller. In contrast, How Git Works explains how Git actually functions. The two are meant to complement each other.

Why Git Is Worth the Effort

Despite the criticism, the zine is a labor of love. Evans highlights several reasons Git remains a favorite tool:

• It's fast.
• It's backwards compatible—commands learned years ago still work.
• Free hosting options like GitHub and GitLab make backups easy.
• Simple workflows are genuinely simple: running git commit -am 'whatever' and git push repeatedly works fine for solo projects.
• Most internal files are plain text, making it possible to understand exactly what is happening under the hood.

Credits and Availability

Evans worked with Marie Claire LeBlanc Flanagan over eight months on the explanations. The cover is by Vladimir Kašiković, with copy editing by Gersande La Flèche and technical review by James Coglan, author of Building Git. Over 60 beta readers provided feedback, setting a record for the publisher.

How Git Works is available here, and the full zine bundle can be purchased here.