From: Julia Evans Date: Tue, 27 Oct 2026 14:30:23 GMT Subject: Re: [PATCH v3 0/2] doc: add new git tutorial Message-ID: In-Reply-To: On Fri, Oct 23, 2026, at 2:01 PM, Ben Knoble wrote: >> Le 23 oct. 2026 à 11:17, Julia Evans via GitGitGadget a écrit : >> >> So far we've gotten 112 comments from 30ish beta testers who have tried to >> learn Git for the first using this tutorial. Most of them were able to >> finish it successfully. By far the most common piece of feedback was that >> people want to learn more about collaboration and branching. I've written a >> draft of a tutorial on branching, but this is already quite a lot of words >> so definitely we can't cover it in this series. >> >> I don't know if it's possible to get this merged quickly, but if it were I >> think it would be amazing since people are so eager for a tutorial on >> branching. If we spend a huge amount of time revising this I think there's a >> real risk I'll run out of funding before we have time to write about >> branching. Ideally I think it would be great if we could merge a "good >> enough" version and then have a way on the website for users to give >> feedback on it, so that we can later incorporate that feedback and >> iteratively make it better over time. >> >> Thanks to Paula, Agavi, Ken Wells, Michael / Chgowiz, Ishmaeel, and all 20 >> or so other test readers. >> >> changes in v3: (v2 was the "first" real version since v1 was a WIP) >> >> * Say that the tutorial supports any version above 2.23.0, when git switch >> was introduced, since the next part of the tutorial on branches will use >> git switch >> * Mention that on Windows the tutorial will work best in Git Bash for and >> it might need adapting for PowerShell. (thanks to Ben) >> * Add a warning about how Git can dump you into vi, how to handle that >> situation, and how to write a longer commit message. I tried to strike a >> balance between lightly suggesting that it might be good to write longer >> commit messages, while making it clear that you can just use -m"" if >> you're not ready to navigate the world of editor configuration. I don't >> think we can use Pro Git here though since it's a bit outdated. (thanks >> to Ben) > > I noticed some discussion in Discord about the main text being out of date, > but while the appendix makes copious references to editors > that have fallen out of style I think it also covers common cases > like VS Code and so on. > >> * Add Helped-by: Ben ... >> * Add output of "ls ~/.ssh/*.pub" (thanks to a test reader) >> * Suggest cat ~/.ssh/whatever.pub to make it clearer how to copy the >> contents of the file. One of the test readers said this was unclear as >> well. (thanks to Junio) >> * Mention that the public key might not be called ed25519.pub (thanks to >> Junio) >> * Add a short section on the importance of git status >> * Fixed the formatting around the headings. Kept it in the same style >> because I had issues with the docs linter when using == DESCRIPTION >> (thanks to Junio) >> * explain what --set-upstream does (thanks to Ben) >> * A few other small phrasing fixes from test readers >> >> non-changes in v3: >> >> * didn't use git config set since the tutorial claims to be compatible with >> Git 2.23.0 >> * kept using the term "folders" since my impression is that Mac OS and >> Windows use the term "folder" and those operating systems are more >> popular than Linux. I don't think any test readers were confused by this >> term, though "directories" might be fine too. >> * leave git init instead of git init myproject so that folks can use the >> same process when setting up Git in an existing project >> >> Julia Evans (2): >> doc: remove gittutorial >> doc: add new Git tutorial for beginners >> >> Documentation/gittutorial.adoc | 1035 ++++++++++++++++++-------------- >> 1 file changed, 573 insertions(+), 462 deletions(-) >> >> >> base-commit: 47fdf2208c5b94c8cc01c106b8f7c85efb91c926 >> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2248%2Fjvns%2Fgit-tutorial-v3 >> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2248/jvns/git-tutorial-v3 >> Pull-Request: https://github.com/gitgitgadget/git/pull/2248 > > The range-diff below looks fine to me! A few small nits, but I don’t > want to hold things up. > >> Range-diff vs v2: >> >> 1: 42035aa84a = 1: 8c0366e996 doc: remove gittutorial >> 2: 6532e60e30 ! 2: d8ea142af6 doc: add new Git tutorial for beginners >> @@ Commit message >> >> Some design choices: >> >> + - Only use commands present in 2.23.0 (when `git switch` as introduced), >> + to support older versions of Git. >> - Introduce a much smaller set of commands than the old tutorial, to >> keep the tutorial quick (doable in an hour). Some users found it to be >> very fast and some wanted to stop early (after step 7) so this seems >> @@ Commit message >> policy if applicable since the "easiest way" may not be the best), and >> giving some instructions for how to translate an HTTPS URL to an SSH >> URL. >> + - Warn people about how `vi` is the default text editor and give some >> + instructions for how to escape >> >> At least 20 people have successfully completed it, and feedback was >> incorporated from problems the testers ran into. >> >> + Helped-by: D. Ben Knoble >> Co-authored-by: Marie Claire LeBlanc Flanagan >> Signed-off-by: Marie Claire LeBlanc Flanagan >> Signed-off-by: Julia Evans >> @@ Documentation/gittutorial.adoc (new) >> +1. Git to be installed. You might already have it installed, >> + and if not there are directions at https://git-scm.com/install/ >> +2. A terminal to use. On Windows, you can use Git Bash which comes >> -+ when you install Git. >> ++ when you install Git. For Windows this tutorial will assume you're >> ++ using Git Bash and if not you might need to adjust some commands like >> ++ `ls` and `cat`. >> + >> +You can check if Git is installed by running this in your terminal: >> + >> @@ Documentation/gittutorial.adoc (new) >> +------------------------------------------------ >> + >> +The exact version isn't too important: this tutorial is designed to work >> -+with any version of Git after 2.0. >> ++with any version of Git after 2.23.0. >> + >> +[[step_2]] >> +Step 2: Introduce yourself to Git >> @@ Documentation/gittutorial.adoc (new) >> +but we're not covering that here. >> + >> +Step 3: Create an empty folder and 1 file >> -+------------------------------------------ >> ++----------------------------------------- >> + >> -+In your terminal, create an empty folder and change directories into it. >> ++In your terminal, create an empty folder and move into it. >> +Later on you could follow the same steps in this tutorial to take an >> +existing project and start managing it with Git, but we're going to use >> +an empty project so that everyone following this tutorial has the exact >> +same files. >> + >> -+For example, run these commands to make a folder called `myproject` >> ++For example, run these commands to make a folder called `myproject`: >> + >> +------------------------------------------------ >> +$ mkdir myproject >> @@ Documentation/gittutorial.adoc (new) >> + >> +You've now stored the first version of your project in Git! >> + >> ++`git status` is very important >> ++------------------------------ >> ++ >> ++`git status` shows you the current state of your Git repository. >> ++It can give a huge amount of different information that takes >> ++practice to interpret, so this tutorial has several examples of >> ++how to interpret the output of `git status` in different situations. >> ++ >> ++It's often useful to run `git status` before and after running a Git >> ++command to see how it changed things. >> ++ >> +Step 6: Make a change >> +--------------------- >> + >> @@ -1,2 +1,2 @@ >> +$ git add example.txt >> +---------- >> + >> -+Then you can run `git commit` to commit it. >> ++Then you can run `git commit` to commit it (though see the warning in >> ++the next section!). >> ++ >> ++Warning about terminal text editors >> ++----------------------------------- >> ++ >> ++If you run `git commit` without any arguments, Git will open a >> ++text editor in the terminal for you to use to edit your commit message. >> ++This lets you write a longer commit message with more details. >> ++By default, Git uses the `vi` text editor, which is extremely difficult > > Personally, I’d drop « extremely » here to avoid casting a judgement? The goal isn't to judge vim (I love vim!), it's to make sure people who aren't familiar with it know that it's not a good idea to try to figure out how to use it in the middle of a tutorial on how to use Git. It's almost impossible for me to imagine someone successfully learning vim when they're unexpectedly put into it for the first time. >> ++to use if you're not used to it. >> ++ >> ++Some signs that you're trapped in `vi`: suddenly typing doesn't work >> ++anymore, and there are tilde `~` characters on the left of the screen. > > Perhaps « bottom-left »; they aren’t in the rows with text, > for example. Good idea, will do. >> ++ >> ++If Git opens `vi` and you'd rather use a different editor, you can >> ++handle it like this: >> ++ >> ++1. Quit by typing `Escape`, then `:q!` and then `Enter` > > I never know if I’m over-indexing on this, but: perhaps > « press the Escape key, type …, and press Enter »? One probably > does not want to type the word Escape ;) Good idea, will do. > Ideally we’d recommend :cquit!, too, to exit with an error > in case the user accidentally edited the buffer and managed to write it, > in which case they may create a commit and the recovery may be confusing. > But POSIX doesn’t require that of vi/ex even though most distros > ship Vim as the implementation. So :q! will have to do. > >> ++2. Run `git config --global core.editor YOUR_PREFERRED_EDITOR` > > This is probably ok for now. Long term I encourage folks to set > EDITOR and/or VISUAL environment variables, so all > programs know what to do, but shell configuration is way > off-topic here :) Yeah. It also depends on whether the user is planning to use a terminal editor at all, I think some folks will choose to use their IDE integration to work with Git and so setting EDITOR might never become relevant in that case.