cheat-sheet: proposal to update graphviz diagrams to git-sim visualizations

[initialcommit-io]

Hello! I noticed on the Git mailing list that the notes from the 2026 Git contributors summit were posted, and that there are currently efforts underway to improve/clarify Git's documentation and learning resources, especially in the leadup to the release of Git 3.0. I would love to help contribute to this.

Some context

I have made some small contributions to Git in the past and have attended multiple contributor summits (mainly as someone deeply interested in Git as opposed to a core contributor), but have mainly spent the past several years working on visual Git tools to help make learning and using Git more intuitive. My main project is called git-sim (https://github.com/initialcommit-com/git-sim), which is an open-source tool enabling users to visually simulate Git commands in their own repos.

I recently updated it to generate lightweight, web-native outputs instead of just image and video files, and now it can visualize a series of consecutive Git commands or even entire sequential workflows.

Why I submitted this PR

After noticing the ongoing efforts to enhance Git's learning resources, I stumbled upon the static graphviz diagrams on the git-scm cheat sheet, and it got me thinking that lightweight animations might help communicate Git concepts even more clearly and align with the team's goals of clarifying Git as much as possible, esp for newer users.

So I put together this PR as a WIP draft / proposal to test out this idea. I swapped out the five graphviz diagrams in the "Combine Diverged Branches" section with animated, interactive Git command sequences generated by git-sim in dummy repos shaped like the original diagrams. See GIFs and screenshots below (note that these GIFs / screenshots are just provided so you can see what it looks like - the actual Git animations are web-native SVGs and HTML are integrated via my pull request). I themed them using existing design language from the cheat sheet page and they are compatible with light/dark mode toggling. (I encourage you to spin it up locally and see how it looks on the cheat sheet page itself, as it's much smoother and more interactive than the GIFs below).

git rebase main

git merge banana

git merge --squash banana

git merge banana (fast-forward)

git cherry-pick <commit>

And here is are some screenshots of what it looks like embedded on the actual cheat sheet page:

What's in the PR

• content/cheat-sheet/_index.html: Update graphviz diagrams to their corresponding git-sim counterparts.
• static/git-sim/cheat-sheet/*.html: The five web-native git-sim command visualizations. They share one stylesheet and one script under static/git-sim/assets/.
• static/js/git-sim-embed.js: The only script loaded globally by the cheat sheet page - loads each simulation into its iframe when scrolled to.
• static/git-sim/assets/git-sim-session.js: Loaded in each simulation's iframe (not globally) to perform animations, handle interactions, and embedded controls.
• assets/sass/cheat-sheet.scss: Small styling updates.

All assets are static and served from git-scm.com. FYI there is a discreet link to the git-sim GitHub page in the "?" help menu on each visualization.

To try it, run hugo serve and open /cheat-sheet.html. git-sim is not needed to build the site.

TO DO / Issues

• The git-sim simulations most-likely break the PDF generation. Right now the PDF would likely show empty slots where the simulations sit.
• Potential build integration so that the git-sim simulations can be regenerated as a part of the build as the content changes, instead of just committing git-sim's output files.
• Licensing messaging since git-sim is GPL-2.0. I am happy to provide whatever is necessary under MIT.

I'd love to hear your thoughts on this and whether you think it would improve the cheat sheet, docs, or Git learning resources. Happy to discuss any changes to design, implementation, or scope 🙂

[dscho]

@jvns I guess this PR and discussion is relevant to your interests.

Personally, I am mostly interested in keeping the printable cheat sheet in a useful and visually-pleasant state... but then, if I was more talented with documentation, Git's manual pages would be in a much better shape, much of them is my fault. So I'll see myself out now.

[jvns]

This is very impressive! My main concerns are:

• How much space the animations take up. For me it's very important that a cheat sheet be visually compact: I think the "combine diverged branches" section is already a little bit too big because it doesn't fit on one screen.
• How this affects whether the cheat sheet can be printed, like @dscho said. I hear from people all the time that they appreciate having a printable cheat sheet
• It's also not obvious to me whether the animations make it clearer what's happening or not. Personally I think I find them harder to understand than just the before/after.

I'd love to hear more about your process for getting feedback from users on GitSim and your interactive visualization work! I've built a lot of interactive playgrounds personally but I find actually doing the playtesting with users to make sure they're getting the value from it is really tricky.

Even if this doesn't have a place in the cheat sheet, I was talking to someone at Git Merge about the idea of building an interactive Git playground on the site (like https://go.dev/play/) where you can run arbitrary Git commands and it gives you a visualization of what each command did. I'm curious about whether Git Sim can do that.

[initialcommit-io]

Thank you @dscho and @jvns for taking a look so quickly and for the great points!

Considering this is a cheat-sheet medium, I definitely went overboard on the size of the diagrams in the PR 😅 , but admittedly didn't spend much time on perfecting this or PDF functionality as this was more to spark a conversation. But both should be fairly easily addressable.

If you don't mind I would like to try another attempt at this by optimizing space, removing unneeded UI elements, and matching the git object size to current graphviz size. I'm also curious now whether I can get it even smaller than the graphviz versions, since the before and after state can be represented on the same diagram (due to the animations showing the state transition on the same graph). Since a PDF can only capture a single state, this would need to be taken into account to expand the before/after states in this case if both are desired.

However the bigger concern for me is what you mentioned @jvns - that you didn't necessarily find the animations to be clearer than the static before/after diagrams, as this would make the compactness discussion moot. I do see your point as there is something intuitive to the brain about seeing a nice simple before/after state simultaneously. However, in my experience there are certain Git concepts that are abstract enough that seeing their "motion" can significantly boost understanding, especially to newer Git users. This especially applies to HEAD (and refs in general), which was one of the most confusing concepts to me when first learning Git as refs can be moved around in very unintuitive ways by various Git commands. At the time my brain just had no idea how to conceive of what a ref really was, which in hindsight is funny/frustrating due to how simple and (to be blunt) "dumb" they are 😄 once you know how Git works under the hood. In my opinion the motion is also helpful for commands where commits "move around" so to speak, such as rebases and cherry-picks, and also how file changes move around in the working dir/index/stash/etc.

So it does make me wonder if there is a happy medium where animations could be used in a thoughtful way where they might be most effective, without just throwing them in needlessly... Let me chew on this a little bit and see what I can come up with...

As a tangent, I'm also curious how you both feel about a "customizability" feature in the cheat sheet - by that I mean users being able to select a subset of commands they need/use the most and download/print those, since users (sometimes) are the ones who know their own situation best, which commands they use the most, which they are constantly looking up.

Regarding a visual Git playground thingy - I have thoughts 😸. The most popular one is likely learn-git-branching, but my biggest qualm with it is that (as far as I know) doesn't operate within the context of the user's repo, so you are really can't match the exact context that Git user's are working in. That context gap is the main one git-sim is designed to fill, but not sure it really matters for what you're envisioning.

Anyway, git-sim can sortof do this. It has a "live mode" which currently is triggered from the terminal within a local git repo by running git-sim live. That opens a web viewer (either on my site or locally) which essentially watches the underlying Git repo and animates any state changes in real time. That is actually how I generated some of sequences in the PR, and the animations can be easily recorded, replayed, and shared later. So theoretically this could be integrated onto a hosted site by hosting temporary generated Git repos behind the scenes. But in a nutshell, git-sim (at least for now) needs a real repo to watch. The benefit of this is that anything git-sim animates in live mode literally happened against a real Git repo, so there is less potential for the tool inventing some non-existing Git functionality. This does make me curious about adding the ability for git-sim to generate ascii / doc-friendly graph output as well, since I believe tools like graphviz and mermaid provide no assurances that the generated graphs are actually valid from a Git perspective...

PS: I was so sad to miss Git merge this year! I loved going the past few years but just couldn't justify going all the way to Portugal this time 😢.

[jvns]

Yeah agreed that the biggest issue is whether the animations are clearer or not.
Especially since it introduces a lot more complexity I think we'd want there to be a big benefit.

... in my experience there are certain Git concepts that are abstract enough that seeing their "motion" can significantly boost understanding, especially to newer Git users.

What's an example in the cheat sheet you think this applies to?

[initialcommit-io]

What's an example in the cheat sheet you think this applies to?

I think if done well, it could apply to all 5 command sequences in the "Combine Diverged Branches" which are all combinations of moving refs, moving/copying commits, and (non-obvious) working dir changes. Outside of that I think it's very helpful for illustrating/differentiating the many types of scenarios git reset can be used for.

I pushed an update to the PR. (see screenshot / GIFs below), along with list of benefits here:

• These are multi step command sequences, so only showing before/after snapshots of the state leaves out information about what each individual command is doing (esp how refs move - note inclusion of HEAD in all animations). I think that makes sense for a printed cheat sheet, but why not make the web version richer by clearly showing what each command in the sequence is doing to accomplish the end result? The updated version highlights the written git command for the step that's currently happening in the animation, and users can click on each individual command in the sequence to replay that part on it's own.
• The updated version of the "Combine Diverged Branches" section takes up ~25% less vertical space in web than the original graphviz version which should let it fit on 1 screen. Comparing side by side, I'd also say its a cleaner, less cluttered presentation than having 2 static diagrams per card that show mostly the same elements. Still would need to figure out exactly how to show on PDF, likely show the original before/after versions there since compacting wouldn't reduce printed size from 2 pages down to 1 anyway.
• The original "Combine with squash merge:" card doesn't convey anything about what's happening in the working directory / index. The animated version shows those files appearing in the index during the --squash step, and names them in a way that can be correlated with the commits they are being squashed from.
• I preserved all of the visual cues used in the graphviz version, like the "<-- lost" label and orange borders / dotted lines.
• The visualizations are interactive (and shareable if desired, but I disabled that for now to have a cleaner UI): the commits/refs can be hovered to add additional useful context via tooltips, showing which commits are now unreachable, sneaking in a definition of "Git HEAD" and that "branches are just fancy labels... yada yada", (can test tooltips locally with the PR code)

Rebase:

Merge:

Merge --squash:

Merge FF:

Cherry-pick: