Re: [PATCH 2/2] doc: add new Git tutorial for beginners
- From
Julia Evans <julia@jvns.ca>
- Date
- Oct 20, 2026, 17:59 UTC
- Message-ID
- <CD1E58AB-4884-4433-9AB8-460FE9A882FC@jvns.ca>
- In-Reply-To
- <xmqqzew8wb3g.fsf@gitster.g>
Show 21 quoted lines
> On Oct 20, 2026, at 1:11 PM, Junio C Hamano <gitster@pobox.com> wrote: > > "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> From: Julia Evans <julia@jvns.ca> >> >> This tutorial covers: >> >> 1. Creating an empty repo with `git init` >> 2. Making commits with `git add`, `git commit`, `git diff`, and >> `git status` >> 3. Pushing to code to a Git host on the internet, including creating an >> SSH key >> >> Signed-off-by: Julia Evans <julia@jvns.ca> >> --- > > The goal is well described, and overall the tutorial is well-paced > and avoids common beginner traps. Since Ben has covered the text > fairly well, the remainder of this message has just some leftover > nitpicks.
Glad to hear it!
Show 30 quoted lines
>> +Step 10: Create an SSH key (if needed) >> +------------------------------------- > > Even though AsciiDoc implementations are somewhat lenient to allow > difference by a char or two, but the number of hyphens there must > match the number of chars on the previous line, so add one '-'. > >> +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. >> + >> +If you don't already have an SSH key, you'll need to create one. On Mac >> +or Linux, you can check if you already have an SSH key by running: >> + >> +------------------------------------------- >> +$ ls ~/.ssh/*.pub >> +------------------------------------------- >> + >> +If you don't already have an SSH key, run: >> + >> +------------------------------------------- >> +$ ssh-keygen >> +------------------------------------------- > > It may depend on the system settings, but doesn't this by default > still create id_rsa.pub? I wonder if we want > > $ ssh-keygen -t ed25519 > > so that it will match what the users will find in the next "Step 11".
I thought so too, but openssh.org says that the default is ed25519 now: https://man.openbsd.org/ssh-keygen.1#t
From the release notes it looks like ed25519 has been the default since 2023: https://www.openssh.org/txt/release-9.5 . I’m not sure what the default was before that, though I also thought the default was still RSA so maybe it was RSA.
I’m inclined to suggest that people just use SSH’s default, since as we move towards post-quantum cryptography, openssh might change its default key type again, and if that happens we’d want folks to use the new default instead of going back to ed25519.
Show 21 quoted lines
>> +Step 11: Tell the Git host your SSH public key
>> +----------------------------------------------
>> +
>> +First, find your SSH key like this (on Mac or Linux):
>> +
>> +-------------------------------------------
>> +$ ls ~/.ssh/*.pub
>> +-------------------------------------------
>> +
>> +That will output something like
>> +
>> +-------------------------------------------
>> +/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").
>
> OK. I hope users won't paste the ls output above instead by
> mistake, but perhaps giving a command like "cat ~/.ssh/id_ed25519.pub"
> may make this step harder to make mistakes?I’ve put it on my list of changes to consider
Show 12 quoted lines
>> +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 >> +under "SSH keys" in your settings. If it asks you what type of SSH key, >> +look for something like "Authentication Key". >> + >> +Once you've done this, you're done! Git will automatically use your SSH >> +key to try to connect. > >> +Step 14: push your changes >> +-------------------------- > > Upcase "Push your changes" to match other steps.
Will do, thanks.