git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] doc: add tutorial on branches for beginners

From
Julia Evans <julia@jvns.ca>
Date
Nov 18, 2026, 12:43 UTC
Message-ID
<09bcad81-4bbf-4849-a3a4-a409f5ee5434@jvns.ca>
In-Reply-To
<pull.2307.git.1794259990263.gitgitgadget@gmail.com>
This tutorial is a bit of a long read, so here are some of my own notes on the branch after a week away from it. Also let me know if I can do anything else to help review this one! My current funding ends Nov. 30, though I'll see this one through without funding if needed.
1. It was a bit tougher to get test readers for this one even though so many people said they were interested in learning about branches and collaboration, and I'm not sure why. Almost everyone who completed it said that it took less than an hour. Maybe a table of contents would help folks understand the overall structure to see what they're getting into?
2. This document is doing a pretty tricky dance where we're introducing some example Git workflows for collaboration without explaining remotes or upstreams, because the tutorial is already quite long, but  ultimately the reason many people use Git is to collaborate and it feels silly to not talk about collaboration at all. I believe we gave at least a basic explanation of everything that is actually used in the example Git workflows but this will definitely leave some people with questions about how remotes work. We don't have a great place to point people to learn more about remotes. In the future it might make sense to write another guide on remotes and upstreams (maybe `git help remotes`?).
3. One of the test readers commented that they were confused by `git switch` because they're familiar with `git checkout`. At first I didn't get it (if someone already knows about `git checkout`, why do they even need to read this tutorial?), but actually some of the test readers had been using Git for quite a long time (even 10+ years) but were still interested in a basic tutorial on branches because they still weren't clear on the basics of how branches work. So it might be better to also mention `git checkout`.
4. Only using `git log --graph` for the branch diagrams is tough and a lot of people hard a hard time understanding the ASCII art diagrams. I didn't see a better option because other ASCII diagrams are not really that much better IMO (you still have to explain them, and they don't have the benefit of being a tool you can actually use to explore your repo). And we don't have prior art for using SVGs in the HTML docs.
- Julia
Previous: Julia Evans
Message 6 of 6 in “doc: add tutorial on branches for beginners”
  1. doc: add tutorial on branches for beginnersJulia Evans via GitGitGadget, Nov 9, 2026
  2. Junio C HamanoNov 9, 2026
  3. Julia EvansNov 9, 2026
  4. Junio C HamanoNov 9, 2026
  5. Julia EvansNov 10, 2026
  6. Julia EvansNov 18, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.