Re: [PATCH v3 0/2] doc: add new git tutorial

["Julia Evans" <julia@jvns.ca>]

On Fri, Oct 23, 2026, at 2:01 PM, Ben Knoble wrote:
>> Le 23 oct. 2026 à 11:17, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> 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 <ben.knoble@gmail.com>
>>          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>
>>     @@ 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.