Skip to content

doc: add tutorial on branches for beginners - #2307

Open
jvns wants to merge 1 commit into
gitgitgadget:masterfrom
jvns:tutorial-branches
Open

doc: add tutorial on branches for beginners#2307
jvns wants to merge 1 commit into
gitgitgadget:masterfrom
jvns:tutorial-branches

Conversation

@jvns

@jvns jvns commented Nov 9, 2026

Copy link
Copy Markdown

Some self-review comments:

  • The section on GUIs is tough to write because a lot of the popular GUIs are proprietary to some extent. Might remove it if that seems like the best way.
  • When the new gittutorial.adoc lands I think it would be good to add a little table of contents to the top of it to match this one's TOC.

Thanks to Mario (bavarianbidi), Johnny, Ken Wells, Yatin Lala, Valentin Bachem, Ozgur Dincer, Ken Wells, matsch, and all the other test readers for giving feedback on this. We got 70 comments from 16 people.

  • Here's the overall feedback from the test readers so far (from "Any other feedback?")
  • As git with all the different concepts, and everything builds on each other is often for new learners hard to follow, I really liked the scope of the tutorial. Just focusing on branches and everything else might be relevant later.
  • This is so good!
  • Thanks for doing this, it's greatly appreciated.
  • It went very fluent. I was surprised at how quickly I was progressing in the text. How the important thing is that I'm going to use what I've learned in practice. A tutorial cannot help directly with that; It can only motivate. Maybe it would be nice to ass a sentence or two on that.
  • Thank you for what you do! 🫶
  • This is the best tutorial for git branches. It was easy to follow and I learned so much. I really appreciated the way that the steps flowed into each other and built off of previous steps, and all the example output matched what I saw on my machine. Up until now I've just been blindly following other people's instructions on how to manage branches, but I finally feel like I get it now. Especially with the different examples at the end; I can see myself in almost all of them and it has given me some ideas on how to manage my small-time projects. Like for modifying other people's repositories, I don't have to keep making new directories, I can just make a new branch and push that branch to my repo! It was such a huge confidence boost to be able to look at the different use cases and be like "I can do that one here, and that one there!" I don't know what could be done to make it better. I might end up printing this out and putting it on the wall for when I'm working on stuff later.
  • I am German. Most of the tutorial was understandable and clear.
  • Not for this one, but I'd love a tutorial on worktrees.
  • Very concise, I learned something new.
  • Really enjoying and appreciating these tutorials, thanks very much
  • The whole tutorial is quite readable and helpful. :)
  • I'm confused of using git switch. I always did what described in the tutorial using git checkout...
  • Thank you for this and the previous tutorial! I've long been interested in using git but found the complete documentation a bit overwhelming. You're breaking it down into easily digestible chunks and I really appreciate it!

cc: Patrick Steinhardt ps@pks.im
cc: "D. Ben Knoble" ben.knoble@gmail.com

@gitgitgadget

gitgitgadget Bot commented Nov 9, 2026

Copy link
Copy Markdown

There is an issue in commit 37349e2:
doc: add tutorial on branches for beginners

  • Lines in the body of the commit messages should be wrapped between 60 and 76 characters.
    Indented lines, and lines without whitespace, are exempt

@jvns
jvns force-pushed the tutorial-branches branch 2 times, most recently from 3f3877c to b3288c1 Compare November 9, 2026 21:30
@jvns Marie Claire LeBlanc Flanagan
doc: add tutorial on branches for beginners
5eaecda 
Because Git's branches are so flexible and the meaning of a branch is
only what people assign to it, it's important to talk about some of the
social context about branches. Do this in two ways:

1. Introduce some imaginary characters who are learning branches for the
   first time and examples of workflows they might use. Test readers
   said this was helpful because it helped them see different ways
   they might use branches.
2. Explain the importance of a "main" or "master" branch in many
   projects, and give a few examples of how projects might use it.

On `git log`:

- Use the output of `git log --graph` to visualize branches instead of
  a more abstract ASCII diagram, since it serves a double purpose of
  teaching people how to read `git log`'s output.
  But also mention that folks may prefer to use a GUI to visualize
  branches.
- Include two sections to explain the output of `git log`, since several
  test readers found it very hard to understand. In that explanation,
  only explain `HEAD` fairly briefly and instead keep the focus on the
  idea of a "current branch", since that's the term Git's UI normally
  uses.

On the conceptual introduction at the beginning:

- One of the biggest issues with explaining branches is that there are 3
  ways in Git to think of branches and it's not straightforward to
  explain how to reconcile them:
  1. just the commits that "branch off"
  2. the latest commit on the branch
  3. the full history since the beginning of time
  Handle this by starting with the "tree" metaphor where branches
  "branch off" a central trunk (way 1), since this makes sense with how
  people actually want to use branches. Point out some issues with the
  tree metaphor and talk about how it relates to the way Git represents
  branches (way 2).
- Avoid using computer science jargon, because it's a major barrier to
  folks without a CS background. It's not useful or realistic to teach
  most beginners the term "directed acyclic graph" just so they can
  learn branches. Mention the term "directed acyclic graph" briefly in a
  note for folks who are already familiar with that term and link folks
  to the data model if they'd like more information.
- Include some basic facts about commits. Folks seemed to find this
  helpful, one person said they didn't realize it would be so hard to
  change their email address later.

To keep it readable:
- Don't assume that the reader has read `gittutorial`, and instead
  refer back to it explicitly if it's relevant.
- Always include the output for every command. Test readers said
  this was helpful.

Other choices about material that is/isn't included:

- `git-prompt.sh` (yes): Mention how important it is to be aware
  what branch you're on, and suggest using `git-prompt.sh`. Link to
  git-prompt.sh on GitHub since several test readers couldn't find it on
  their machine. The test readers liked this.
- fast-forward merges (yes): Explain the difference between a fast-forward
  merge and a merge commit by giving examples of what each one looks
  like.
- upstreams/rebase (no): Don't explain what an upstream is or introduce
  rebase, since we're already introducing a lot of concepts. Instead
  include a "Where to learn more" section with some pointers to where to
  continue learning.
- GUIs (yes): Some readers wanted a suggestion for what GUI to use. It's
  very hard to suggest an appropriate GUI because there are so many and
  so many of them are not open source, but give a couple of suggestions
  of open source tools that seem to be popular with the community. Also
  mention that many non-open-source IDEs have built-in Git integrations
  for folks who are already using those tools who might not be aware,
  since they're a popular way to use Git.

Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Julia Evans <julia@jvns.ca>
@jvns
jvns force-pushed the tutorial-branches branch from b3288c1 to 5eaecda Compare November 9, 2026 21:30
@jvns

jvns commented Nov 9, 2026

Copy link
Copy Markdown
Author

/submit

@gitgitgadget

gitgitgadget Bot commented Nov 9, 2026

Copy link
Copy Markdown

Submitted as pull.2307.git.1794259990263.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2307/jvns/tutorial-branches-v1

To fetch this version to local tag pr-2307/jvns/tutorial-branches-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2307/jvns/tutorial-branches-v1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jvns