From: Julia Evans <julia@jvns.ca>
To: Julia Evans via GitGitGadget <gitgitgadget@gmail.com>,
git@vger.kernel.org
Cc: Patrick Steinhardt <ps@pks.im>, "D. Ben Knoble" <ben.knoble@gmail.com>
Subject: Re: [PATCH] doc: add tutorial on branches for beginners
Date: Wed, 18 Nov 2026 07:43:52 -0500 [thread overview]
Message-ID: <09bcad81-4bbf-4849-a3a4-a409f5ee5434@jvns.ca> (raw)
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
prev parent reply other threads:[~2026-11-18 12:43 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-09 21:33 [PATCH] doc: add tutorial on branches for beginners Julia Evans via GitGitGadget
2026-11-09 21:56 ` Junio C Hamano
2026-11-09 22:01 ` Julia Evans
2026-11-09 22:11 ` Junio C Hamano
2026-11-10 14:31 ` Julia Evans
2026-11-18 12:43 ` Julia Evans [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=09bcad81-4bbf-4849-a3a4-a409f5ee5434@jvns.ca \
--to=julia@jvns.ca \
--cc=ben.knoble@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=ps@pks.im \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox