doc: add tutorial on branches for beginners

From: Julia Evans <[email protected]>

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.

---
doc: add tutorial on branches for beginners

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!

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2307%2Fjvns%2Ftutorial-branches-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2307/jvns/tutorial-branches-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2307

 Documentation/Makefile                  |   1 +
 Documentation/gittutorial-branches.adoc | 940 ++++++++++++++++++++++++
 Documentation/meson.build               |   1 +
 command-list.txt                        |   1 +
 4 files changed, 943 insertions(+)
 create mode 100644 Documentation/gittutorial-branches.adoc

index b574ca2044..4f3fc9a97f 100644
@@ -65,6 +65,7 @@ MAN7_TXT += gitremote-helpers.adoc
 MAN7_TXT += gitrevisions.adoc
 MAN7_TXT += gitsubmodules.adoc
 MAN7_TXT += gittutorial-2.adoc
+MAN7_TXT += gittutorial-branches.adoc
 MAN7_TXT += gittutorial.adoc
 MAN7_TXT += gitworkflows.adoc
 

index b290557834..23634ebd7e 100644
@@ -208,6 +208,7 @@ manpages = {
   'gitrevisions.adoc' : 7,
   'gitsubmodules.adoc' : 7,
   'gittutorial-2.adoc' : 7,
+  'gittutorial-branches.adoc' : 7,
   'gittutorial.adoc' : 7,
   'gitworkflows.adoc' : 7,
 }

index 56d0d7ed9b..0e3e3fc378 100644
@@ -245,6 +245,7 @@ gitrepository-layout                    userinterfaces
 gitrevisions                            userinterfaces
 gitsubmodules                           guide
 gittutorial                             guide
+gittutorial-branches                    guide
 gitweb                                  ancillaryinterrogators
 gitworkflows                            guide
 scalar                                  mainporcelain

base-commit: 3c60ef1e38ee80337025a1b908327f7879386329

gitgitgadget

A meta-comment, not limited to this patch.

We are currently reviewer-bandwidth-limited. Having many topics in-flight under review would not help these topics go any faster with greater parallelism. In fact, it slows everything down by wearing available reviewers down due to forced context switching.

I wonder what incentives, carrots and sticks we have on those who have in-flight topics that are so close to the finish line to concentrate on completing these topics before sending new ones.

Ideas?

For sure, I can avoid submitting new topics in the future until the current ones are finished. I don't have any other changes in progress in any case.

I'm very conscious that reviewer bandwidth is limited and I'm very interested in ideas for how to make the docs review process easier.

- Julia

My interest in making review process better is not limited to documentation patches, though.

Thanks.

When I applied for funding from the Sovereign Tech Agency to work on the Git project's documentation, the main risk I flagged in my application was that reviewer capacity in the project is very limited. I tried to deal with this in a several ways:

1. I emailed a few people who had reviewed my patches in the past to ask if they would be have capacity to do review on the new patches. Patrick and Ben agreed to do some reviews which I really appreciate.
2. I applied for a relatively small amount of funding, which limits how many hours Marie and I actually spent writing. Fewer hours spent writing means less work to review :)
3. We recruited dozens of test readers to participate in a kind of side review process. That doesn't serve the same function as the mailing list review of course, but it hugely improves the final quality of the document without introducing extra pressure on Git project's reviewers.

I don't know which of these strategies would apply to code changes but those are some of things I've tried so far.