git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
Date
Oct 30, 2026, 20:56 UTC
Message-ID
<pull.2248.v5.git.1793393787.gitgitgadget@gmail.com>
In-Reply-To
<pull.2248.git.1791315422.gitgitgadget@gmail.com>

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)
 * 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
changes in v4:
Make the instructions more Windows-friendly (thanks to Richard Kerry), by:
 * mentioning that Git for Windows will ask you to configure a text editor
   when you install it
 * saying that the SSH instructions are Mac/Linux only and suggesting using
   Git Credential Manager on Windows, and update the instructions for
   whether to use an HTTPS/SSH URL accordingly
 * using "folder" instead of "directory" in a few more places Also:
 * Say "bottom left" (thanks to Ben)
 * Add a link to how to configure various text editors
   https://git-scm.com/book/en/v2/Appendix-C:-Git-Commands-Setup-and-Config#ch_core_editor
   (thanks to Ben)
non-changes in v4:
 * leave the comment about how vim is "extremely difficult if you're not
   used to it" alone, I couldn't come up with a better way to communicate it
   and I really don't want anyone to think that being able to use vim is
   expected.
changes in v5:
 * replace "it" with "GCM" in the commit message
 * remove some trailing whitespace the CI on GitHub told me about (make
   check-docs doesn't seem to check for this)
Julia Evans (2):
  doc: remove gittutorial
  doc: add new Git tutorial for beginners
 Documentation/gittutorial.adoc | 1051 ++++++++++++++++++--------------
 1 file changed, 589 insertions(+), 462 deletions(-)
base-commit: 47fdf2208c5b94c8cc01c106b8f7c85efb91c926
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2248%2Fjvns%2Fgit-tutorial-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2248/jvns/git-tutorial-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/2248
Range-diff vs v4:
 1:  64d9811539 = 1:  64d9811539 doc: remove gittutorial
 2:  4b40588c90 ! 2:  051b2c4551 doc: add new Git tutorial for beginners
     @@ Commit message
            giving some instructions for how to translate an HTTPS URL to an SSH
            URL.
          - Use Git Credential Manager for authentication on Windows, since it's
     -      simpler, SSH auth is a very "unixy" thing to do,  and it comes with
     +      simpler, SSH auth is a very "unixy" thing to do,  and GCM comes with
            Git for Windows
          - Warn people about how `vi` is the default text editor and give some
            instructions for how to escape
     @@ -1,2 +1,2 @@
      +On Windows, you can skip this step and the next one because Git for
      +Windows comes with
      +https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager]
     -+to handle logging in. 
     ++to handle logging in.
      +
      +If you don't already have an SSH key, you'll need to create one.
      +You can check if you already have an SSH key by running:
-- 
gitgitgadget
Previous: Junio C HamanoNext: Julia Evans via GitGitGadget
Message 51 of 53 in “WIP: doc: add new git tutorial”
  1. 0/2 WIP: doc: add new git tutorialJulia Evans via GitGitGadget, Oct 6, 2026
  2. 1/2 doc: remove gittutorialJulia Evans via GitGitGadget, Oct 6, 2026
  3. 2/2 doc: add new Git tutorial for beginnersJulia Evans via GitGitGadget, Oct 6, 2026
  4. D. Ben KnobleOct 7, 2026
  5. Julia EvansOct 19, 2026
  6. Ben KnobleOct 19, 2026
  7. Julia EvansOct 19, 2026
  8. D. Ben KnobleOct 19, 2026
  9. Junio C HamanoOct 20, 2026
  10. Julia EvansOct 20, 2026
  11. Junio C HamanoOct 20, 2026
  12. Junio C HamanoOct 20, 2026
  13. Junio C HamanoOct 20, 2026
  14. Junio C HamanoOct 20, 2026
  15. Junio C HamanoOct 21, 2026
  16. Julia EvansOct 21, 2026
  17. Julia EvansOct 20, 2026
  18. Junio C HamanoOct 20, 2026
  19. Richard KerryOct 26, 2026
  20. Julia EvansOct 26, 2026
  21. Julia EvansOct 26, 2026
  22. Junio C HamanoOct 26, 2026
  23. Julia EvansOct 26, 2026
  24. Junio C HamanoOct 26, 2026
  25. D. Ben KnobleOct 7, 2026
  26. 0/2 doc: add new git tutorialJulia Evans via GitGitGadget, Oct 19, 2026
  27. 1/2 doc: remove gittutorialJulia Evans via GitGitGadget, Oct 19, 2026
  28. 2/2 doc: add new Git tutorial for beginnersJulia Evans via GitGitGadget, Oct 19, 2026
  29. Junio C HamanoOct 20, 2026
  30. Ben KnobleOct 20, 2026
  31. Julia EvansOct 20, 2026
  32. Tuomas AholaOct 20, 2026
  33. Junio C HamanoOct 20, 2026
  34. 0/2 doc: add new git tutorialJulia Evans via GitGitGadget, Oct 23, 2026
  35. 1/2 doc: remove gittutorialJulia Evans via GitGitGadget, Oct 23, 2026
  36. 2/2 doc: add new Git tutorial for beginnersJulia Evans via GitGitGadget, Oct 23, 2026
  37. Ben KnobleOct 23, 2026
  38. Julia EvansOct 27, 2026
  39. Ben KnobleOct 27, 2026
  40. Julia EvansOct 27, 2026
  41. 0/2 doc: add new git tutorialJulia Evans via GitGitGadget, Oct 28, 2026
  42. 1/2 doc: remove gittutorialJulia Evans via GitGitGadget, Oct 28, 2026
  43. Junio C HamanoOct 28, 2026
  44. Julia EvansOct 30, 2026
  45. Junio C HamanoOct 30, 2026
  46. 2/2 doc: add new Git tutorial for beginnersJulia Evans via GitGitGadget, Oct 28, 2026
  47. Junio C HamanoOct 28, 2026
  48. Julia EvansOct 30, 2026
  49. Junio C HamanoOct 30, 2026
  50. Junio C HamanoOct 30, 2026
  51. 0/2 doc: add new git tutorialJulia Evans via GitGitGadget, Oct 30, 2026
  52. 1/2 doc: remove gittutorialJulia Evans via GitGitGadget, Oct 30, 2026
  53. 2/2 doc: add new Git tutorial for beginnersJulia Evans via GitGitGadget, Oct 30, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.