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

Re: [PATCH v4 2/2] doc: add new Git tutorial for beginners

From
Julia Evans <julia@jvns.ca>
Date
Oct 30, 2026, 20:35 UTC
Message-ID
<13af97a1-a86c-4077-9136-204c74f3d625@app.fastmail.com>
In-Reply-To
<xmqqpkwtag8d.fsf@gitster.g>
On Wed, Oct 28, 2026, at 1:26 PM, Junio C Hamano wrote:
Show 49 quoted lines
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Julia Evans <julia@jvns.ca>
>>
>> Introduce Git in two parts:
>>
>> Steps 1-7: Create an empty repo & make 2 commits (`git init`,
>> `git add`, `git commit`, `git status`, `git diff`)
>> Steps 8-12: Push the repo to a remote host like GitHub or GitLab
>> (`git remote add`, `git push`)
>>
>> 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
>>   to be a good balance.
>> - Have users start with an empty repository instead of an existing
>>   project, because many of the testers did not have an existing project
>>   to test, or were scared of using an existing project.
>> - Add a troubleshooting section, since in the testing some users got
>>   extremely stuck (for 4+ hours) on minor issues like needing to say
>>   "yes" when SSHing to a new host.
>> - Don't explain branches, because explaining branches and collaboration
>>   is complicated and deserves its own tutorial. Instead just tell users
>>   we're not going to explain them in this document.
>> - Tell users to set their default branch to `main`, because many Git
>>   hosts use it as their default branch and it really simplifies things.
>> - Keep it as vendor neutral as possible, while acknowledging the reality
>>   that Git hosting services like GitHub, GitLab, etc are extremely
>>   popular. Do this by creating the repo locally and then optionally
>>   pushing it later.
>> - Use SSH for authentication, explaining how to set up SSH in the
>>   easiest way possible (with disclaimers to check your security team's
>>   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.
>> - 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
>>   Git for Windows
>
> What does "it" in "and it comes with" refer to?  It is unclear
> between GCM or SSH and since SSH appeared later, it tempts readers
> to think that it says "and SSH comes with GfW".  But the early part
> of the same sentence says SSH is "unixy", which probably was used as
> a synonym to "non-Windowsy", implying that we do not want to
> recommend it.  It gives a conflicting and confused message.
Will replace "it" with "GCM".
Show 17 quoted lines
>   - Use GCM for authentication on Windows, since it comes with GfW,
>     and is simpler than SSH authentication.
>
>> +Step 10 (Mac/Linux only): 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
>> +with an SSH key.
>> +
>> +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. 
>
> This is the only mention of GCM.  As described in step 14 (push),
> GCM will kick in when needed.  It is great that Windows users do not
> need any handholding beyond this line ;-)

I hope so! I found a friend with a Windows computer to test this and it did work as advertised. If there are issues hopefully we'll hear from folks about it and we can adjust :)

Previous: Junio C HamanoNext: Junio C Hamano
Message 48 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.