Re: [PATCH 2/2] doc: add new Git tutorial for beginners
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 20, 2026, 17:11 UTC
- Message-ID
- <xmqqzew8wb3g.fsf@gitster.g>
- In-Reply-To
- <41dca2e8e0c5fadb8ad9ed8707029356e56cc540.1791315422.git.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 12 quoted lines
> 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.
> +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 '-'.
Show 16 quoted lines
> +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".
Show 17 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?
Show 7 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.