From: Ben Knoble Date: Fri, 23 Oct 2026 18:01:19 GMT Subject: Re: [PATCH v3 0/2] doc: add new git tutorial Message-ID: In-Reply-To: > 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? > ++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. > ++ > ++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 ;) 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 :) > ++ to configure which editor to use. For example, `nano` is available > ++ on a lot of systems and has basic instructions on the screen for how > ++ to use it. > ++3. Run `git commit` again > ++ > ++If you don't want to set up a text editor yet, you can also just use > ++`git commit -m"your message"` like we did earlier in this tutorial. > + > +Step 8: Make a change and throw it away > +--------------------------------------- > @@ -1,2 +1,2 @@ > +This "working tree clean" message means that there haven't been any > +changes since your last commit. > + > -+Now make a change to your code, and run `git status` again. Like last > ++Now make a change to `README.md`, and run `git status` again. Like last > +time, you should see a message like this: > + > +------------------------------------------------ > @@ -1,2 +1,2 @@ > +source Git forge software to your server. > + > +Step 10: Create an SSH key (if needed) > -+------------------------------------- > ++-------------------------------------- > + > +For Git to upload changes to another Git repository, it needs a way to > +login to that repository. One of the most popular ways to do this is > @@ -1,2 +1,2 @@ > +$ ls ~/.ssh/*.pub > +------------------------------------------- > + > -+That will output something like > ++That will output something like this. The exact filename depends on the type > ++of key. The important thing is that you're looking for a filename that > ++ends in `.pub` ("pub" stands for "public"): > + > +------------------------------------------- > +/home/alice/.ssh/id_ed25519.pub > +------------------------------------------- > + > -+Copy the contents of that file to your clipboard. It's important that > -+the filename ends in `.pub` ("pub" stands for "public"). > ++Copy the contents of that file to your clipboard. One way to do that is > ++to run this command (replacing the filename with the right filename), > ++and then copy the output. > ++ > ++------------------------------------------- > ++cat /home/alice/.ssh/id_ed25519.pub > ++------------------------------------------- > + > +Then login to your account on the Git host you chose and paste the SSH > +key into the appropriate place. Depending on the Git host, it's likely > @@ -1,2 +1,2 @@ > +------------------------------------------- > + > +[[step_14]] > -+Step 14: push your changes > ++Step 14: Push your changes > +-------------------------- > + > +Finally, we're ready to send the information in your local Git repository > @@ -1,2 +1,2 @@ > +You should be able to fix this by redoing <>. > +Then <> should work. > + > -+MORE USEFUL GIT COMMANDS > ++More useful Git commands > +------------------------ > + > +We're not going to cover collaboration at all in this tutorial, but here are a > @@ -1,2 +1,2 @@ > + If you see a commit with `git log` that you want more details about, > + you can run `git show COMMIT_ID` to see what changes that made since > + the previous commit (linkgit:git-show[1]) > -+ > -+SEE ALSO > -+-------- > -+linkgit:git-help[1], > ++* To get a list of common Git commands, run `git help` (linkgit:git-help[1]) > + > +GIT > +--- > > -- > gitgitgadget