[PATCH 0/2] WIP: doc: add new git tutorial

This is the first draft of a tutorial which introduces Git in two parts:

Part 1: Create an empty repo & make 2 commits (git init, git add, git commit, git status, git diff) Part 2: Push the repo to a remote host like GitHub or GitLab (git remote add, git push)

So far we've gotten 112 comments from 22 beta testers who have tried to learn Git for the first using this tutorial. Most of them were able to finish it successfully. I'd like to avoid getting into the details of every single thing in the tutorial at this stage (we're still planning to do a second round of feedback with the beta testers, and the beginning especially will likely change)

There are 2 questions I'd like feedback on since they both could affect the structure of the tutorial. I don't think either of these is a dealbreaker, since folks generally were able to finish the tutorial despite all these issues and said that they enjoyed it and learned a lot. But it would be great if there were an easy way to make the process less messy.

question 1: create the repo on the command line, or in the forge? =================================================================

One issue that came up a lot in our testing is that the tutorials explains how to run git init in a repo to create it locally and then later choose a forge to host that repo (GitLab, GitHub, etc) and push to the remote on that forge.

Several users ran into the issue that GitLab by default creates a README.md, which means that when you run your first git push, the push fails since there's already a commit.

A few options I see:

a. Suggest that they instead create the repo on the forge and then clone it. I think this is easier and usually I support suggesting things that are easier, but in this case I think it's our role (as the official Git documentation) to make it clear that you do not need a forge to use Git. IMO this approach really confuses that issues and makes it seem like the forge is more important than it is. b. Suggest git push --force. This is an easy fix but I don't like suggesting that people use --force so early since it's so dangerous. c. Just try to get users to try to figure the right way in the GitLab/GitHub/etc UI to actually create an empty repository that it's possible to just push to. This is really hard because the UIs constantly change.

current solution 1 ==================

Right now we're working on Option C since it seems least bad

question 2: How to handle authentication ========================================

 * How should the tutorial tell users to authenticate? I know there are
   commands like gh auth login for GitHub and IIRC GitLab and it seems like
   there are some advantages to using those, but also AFAIK they're all
   pretty specific to the individual Git forge and I don't see how it's
   possible to discuss them in a generic tutorial.
 * Whether to explain the process of creating an SSH key etc. Arguably this
   is the job of the SSH documentation, but since https://www.openssh.org/
   doesn't have such a guide, it feels bad to tell users "you should go read
   a guide on how to use SSH to do this but by the way that guide does not
   exist so good luck I guess".
 * A lot of testers found it hard to find the SSH URL on GitLab/GitHub

current solution 2 ==================

Right now we're solving these by:

 1. Using SSH
 2. 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)
 3. Giving some instructions for how to translate an HTTPS URL to an SSH URL

Julia Evans (2):
  doc: remove gittutorial
  doc: add new Git tutorial for beginners

 Documentation/gittutorial.adoc | 854 +++++++++++++++------------------
 1 file changed, 397 insertions(+), 457 deletions(-)

base-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2248%2Fjvns%2Fgit-tutorial-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2248/jvns/git-tutorial-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2248