From: Julia Evans Date: Fri, 30 Oct 2026 20:35:00 GMT Subject: Re: [PATCH v4 2/2] doc: add new Git tutorial for beginners Message-ID: <13af97a1-a86c-4077-9136-204c74f3d625@app.fastmail.com> In-Reply-To: On Wed, Oct 28, 2026, at 1:26 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" writes: > >> From: Julia Evans >> >> 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". > - 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 :)