From: Julia Evans <julia@jvns.ca>

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>

Submitted-As: https://lore.kernel.org/git/pull.2307.git.1794259990263.gitgitgadget@gmail.com