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

[Junio C Hamano <gitster@pobox.com>]

"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.

> +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".

> +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?

> +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.