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

[Ben Knoble <ben.knoble@gmail.com>]

> 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?

>     ++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 <<step_12,Step 12>>.
>      +Then <<step_14,Step 14>> 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