Git development
 help / color / mirror / Atom feed
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


      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