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

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

So far we've gotten 112 comments from 30ish beta testers who have tried to
learn Git for the first using this tutorial. Most of them were able to
finish it successfully. By far the most common piece of feedback was that
people want to learn more about collaboration and branching. I've written a
draft of a tutorial on branching, but this is already quite a lot of words
so definitely we can't cover it in this series.

I don't know if it's possible to get this merged quickly, but if it were I
think it would be amazing since people are so eager for a tutorial on
branching. If we spend a huge amount of time revising this I think there's a
real risk I'll run out of funding before we have time to write about
branching. Ideally I think it would be great if we could merge a "good
enough" version and then have a way on the website for users to give
feedback on it, so that we can later incorporate that feedback and
iteratively make it better over time.

Thanks to Paula, Agavi, Ken Wells, Michael / Chgowiz, Ishmaeel, and all 20
or so other test readers.

changes in v3: (v2 was the "first" real version since v1 was a WIP)

 * Say that the tutorial supports any version above 2.23.0, when git switch
   was introduced, since the next part of the tutorial on branches will use
   git switch
 * Mention that on Windows the tutorial will work best in Git Bash for and
   it might need adapting for PowerShell. (thanks to Ben)
 * Add a warning about how Git can dump you into vi, how to handle that
   situation, and how to write a longer commit message. I tried to strike a
   balance between lightly suggesting that it might be good to write longer
   commit messages, while making it clear that you can just use -m"" if
   you're not ready to navigate the world of editor configuration. I don't
   think we can use Pro Git here though since it's a bit outdated. (thanks
   to Ben)
 * Add Helped-by: Ben ...
 * Add output of "ls ~/.ssh/*.pub" (thanks to a test reader)
 * Suggest cat ~/.ssh/whatever.pub to make it clearer how to copy the
   contents of the file. One of the test readers said this was unclear as
   well. (thanks to Junio)
 * Mention that the public key might not be called ed25519.pub (thanks to
   Junio)
 * Add a short section on the importance of git status
 * Fixed the formatting around the headings. Kept it in the same style
   because I had issues with the docs linter when using == DESCRIPTION
   (thanks to Junio)
 * explain what --set-upstream does (thanks to Ben)
 * A few other small phrasing fixes from test readers

non-changes in v3:

 * didn't use git config set since the tutorial claims to be compatible with
   Git 2.23.0
 * kept using the term "folders" since my impression is that Mac OS and
   Windows use the term "folder" and those operating systems are more
   popular than Linux. I don't think any test readers were confused by this
   term, though "directories" might be fine too.
 * leave git init instead of git init myproject so that folks can use the
   same process when setting up Git in an existing project

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

 Documentation/gittutorial.adoc | 1035 ++++++++++++++++++--------------
 1 file changed, 573 insertions(+), 462 deletions(-)


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

Range-diff vs v2:

 1:  42035aa84a = 1:  8c0366e996 doc: remove gittutorial
 2:  6532e60e30 ! 2:  d8ea142af6 doc: add new Git tutorial for beginners
     @@ Commit message
      
          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
     @@ Commit message
            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.
     +    - Warn people about how `vi` is the default text editor and give some
     +      instructions for how to escape
      
          At least 20 people have successfully completed it, and feedback was
          incorporated from problems the testers ran into.
      
     +    Helped-by: D. Ben Knoble <ben.knoble@gmail.com>
          Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
          Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
          Signed-off-by: Julia Evans <julia@jvns.ca>
     @@ Documentation/gittutorial.adoc (new)
      +1. Git to be installed. You might already have it installed,
      +   and if not there are directions at https://git-scm.com/install/
      +2. A terminal to use. On Windows, you can use Git Bash which comes
     -+   when you install Git.
     ++   when you install Git. For Windows this tutorial will assume you're
     ++   using Git Bash and if not you might need to adjust some commands like
     ++   `ls` and `cat`.
      +
      +You can check if Git is installed by running this in your terminal:
      +
     @@ Documentation/gittutorial.adoc (new)
      +------------------------------------------------
      +
      +The exact version isn't too important: this tutorial is designed to work
     -+with any version of Git after 2.0.
     ++with any version of Git after 2.23.0.
      +
      +[[step_2]]
      +Step 2: Introduce yourself to Git
     @@ Documentation/gittutorial.adoc (new)
      +but we're not covering that here.
      +
      +Step 3: Create an empty folder and 1 file
     -+------------------------------------------
     ++-----------------------------------------
      +
     -+In your terminal, create an empty folder and change directories into it.
     ++In your terminal, create an empty folder and move into it.
      +Later on you could follow the same steps in this tutorial to take an
      +existing project and start managing it with Git, but we're going to use
      +an empty project so that everyone following this tutorial has the exact
      +same files.
      +
     -+For example, run these commands to make a folder called `myproject`
     ++For example, run these commands to make a folder called `myproject`:
      +
      +------------------------------------------------
      +$ mkdir myproject
     @@ Documentation/gittutorial.adoc (new)
      +
      +You've now stored the first version of your project in Git!
      +
     ++`git status` is very important
     ++------------------------------
     ++
     ++`git status` shows you the current state of your Git repository.
     ++It can give a huge amount of different information that takes
     ++practice to interpret, so this tutorial has several examples of
     ++how to interpret the output of `git status` in different situations.
     ++
     ++It's often useful to run `git status` before and after running a Git
     ++command to see how it changed things.
     ++
      +Step 6: Make a change
      +---------------------
      +
     @@ -1,2 +1,2 @@
      +$ git add example.txt
      +----------
      +
     -+Then you can run `git commit` to commit it.
     ++Then you can run `git commit` to commit it (though see the warning in
     ++the next section!).
     ++
     ++Warning about terminal text editors
     ++-----------------------------------
     ++
     ++If you run `git commit` without any arguments, Git will open a
     ++text editor in the terminal for you to use to edit your commit message.
     ++This lets you write a longer commit message with more details.
     ++By default, Git uses the `vi` text editor, which is extremely difficult
     ++to use if you're not used to it.
     ++
     ++Some signs that you're trapped in `vi`: suddenly typing doesn't work
     ++anymore, and there are tilde `~` characters on the left of the screen.
     ++
     ++If Git opens `vi` and you'd rather use a different editor, you can
     ++handle it like this:
     ++
     ++1. Quit by typing `Escape`, then `:q!` and then `Enter`
     ++2. Run `git config --global core.editor YOUR_PREFERRED_EDITOR`
     ++   to configure which editor to use. For example, `nano` is available
     ++   on a lot of systems and has basic instructions on the screen for how
     ++   to use it.
     ++3. Run `git commit` again
     ++
     ++If you don't want to set up a text editor yet, you can also just use
     ++`git commit -m"your message"` like we did earlier in this tutorial.
      +
      +Step 8: Make a change and throw it away
      +---------------------------------------
     @@ -1,2 +1,2 @@
      +This "working tree clean" message means that there haven't been any
      +changes since your last commit.
      +
     -+Now make a change to your code, and run `git status` again. Like last
     ++Now make a change to `README.md`, and run `git status` again. Like last
      +time, you should see a message like this:
      +
      +------------------------------------------------
     @@ -1,2 +1,2 @@
      +source Git forge software to your server.
      +
      +Step 10: 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
     @@ -1,2 +1,2 @@
      +$ ls ~/.ssh/*.pub
      +-------------------------------------------
      +
     -+That will output something like
     ++That will output something like this. The exact filename depends on the type
     ++of key. The important thing is that you're looking for a filename that
     ++ends in `.pub` ("pub" stands for "public"):
      +
      +-------------------------------------------
      +/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").
     ++Copy the contents of that file to your clipboard. One way to do that is
     ++to run this command (replacing the filename with the right filename),
     ++and then copy the output.
     ++
     ++-------------------------------------------
     ++cat /home/alice/.ssh/id_ed25519.pub
     ++-------------------------------------------
      +
      +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
     @@ -1,2 +1,2 @@
      +-------------------------------------------
      +
      +[[step_14]]
     -+Step 14: push your changes
     ++Step 14: Push your changes
      +--------------------------
      +
      +Finally, we're ready to send the information in your local Git repository
     @@ -1,2 +1,2 @@
      +You should be able to fix this by redoing <<step_12,Step 12>>.
      +Then <<step_14,Step 14>> should work.
      +
     -+MORE USEFUL GIT COMMANDS
     ++More useful Git commands
      +------------------------
      +
      +We're not going to cover collaboration at all in this tutorial, but here are a
     @@ -1,2 +1,2 @@
      +  If you see a commit with `git log` that you want more details about,
      +  you can run `git show COMMIT_ID` to see what changes that made since
      +  the previous commit (linkgit:git-show[1])
     -+
     -+SEE ALSO
     -+--------
     -+linkgit:git-help[1],
     ++* To get a list of common Git commands, run `git help` (linkgit:git-help[1])
      +
      +GIT
      +---

-- 
gitgitgadget