Repository navigation
Conversation
|
There is an issue in commit ef6bac7:
|
|
There are issues in commit 7e001f0:
|
|
There are issues in commit b88b987:
|
|
There are issues in commit 2147e8b:
|
|
There are issues in commit 3ce896a:
|
|
There are issues in commit 234110d:
|
|
There are issues in commit e4eba93:
|
|
There are issues in commit 72617f0:
|
|
There are issues in commit e162372:
|
|
There are issues in commit 679adf2:
|
|
There are issues in commit 53c4ac6:
|
|
There are issues in commit 7e35ef4:
|
|
There are issues in commit 45e2fca:
|
|
There is an issue in commit 503c90f:
|
|
There are issues in commit 3cfae9b:
|
jvns
force-pushed
the
git-tutorial
branch
3 times, most recently
from
October 6, 2026 19:25
2598f8e to
41dca2e
Compare
Author
|
/submit |
|
Submitted as pull.2248.git.1791315422.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
"D. Ben Knoble" wrote on the Git mailing list (how to reply to this email): On Tue, Oct 6, 2026 at 3:40 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> 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?
> =================================================================
> 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
> ========================================
> 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
Disclaimer, I haven't read the patches yet.
Both of these approaches sound like the right one to me. Assuming
we're suggesting up-to-date key algorithms for SSH, I think that
should be fine. (Memory says ECDSA and ED22519, I think? I'm not sure
about the differences, but my regularly-used keys are the latter and
my newest is the former.)
I happen to use a somewhat convoluted "new key for each host" policy
for myself, which ends up with lots of "Host <host> IdentifyFile
<key>" in ~/.ssh/config and "Include"d files. I think separate keys
per host is a good idea, but I certainly wouldn't want to foist that
mess on new users. OTOH, even leaving an admonition "you probably want
to set up one key per host later, so consider this just a starting
point" is how such starting points become prolific use practice ;)
So, idk on that front. Probably it's over-complicated to do that here,
and point to better guides (or worry about making one externally if
none exist), leaving the admonition in.
Thanks for letting me think aloud,
Ben |
|
User |
|
"D. Ben Knoble" wrote on the Git mailing list (how to reply to this email) regarding 41dca2e: On Tue, Oct 6, 2026 at 3:37 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> 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>
> ---
> Documentation/gittutorial.adoc | 616 +++++++++++++++++++++++++++++++++
> 1 file changed, 616 insertions(+)
> create mode 100644 Documentation/gittutorial.adoc
>
> diff --git a/Documentation/gittutorial.adoc b/Documentation/gittutorial.adoc
> new file mode 100644
> index 0000000000..617dbae096
> --- /dev/null
> +++ b/Documentation/gittutorial.adoc
> @@ -0,0 +1,616 @@
> +gittutorial(7)
> +==============
> +
> +NAME
> +----
> +gittutorial - Introduction to Git for beginners
> +
> +DESCRIPTION
> +-----------
> +
> +This tutorial explains how to import a project's code into Git, make
> +changes to it, and upload the project to the Internet.
> +
> +We'll show you how to use the commands `git commit`, `git add`,
> +`git diff`, `git status`, and `git push`.
> +
> +Command line vs GUI
> +-------------------
> +
> +Git is a command line program, but there are many excellent GUIs for
> +Git built by the community. For example, if you use an IDE to edit your
> +code, it might already have a built-in Git integration that you can use.
> +
> +In this tutorial, we'll give instructions for the command line version
> +of Git, but you can also follow along in a GUI. You can also do some
> +tasks in a GUI and some tasks on the command line. It's up to you.
Since we assume a *nix-ish environment, should we mention that this
tutorial works best on UNIX-like OSs, or in a Git-for-Windows Bash
environment, and may need adapting for folks using PowerShell, CMD, or
some other userspace (not a piece of jargon I would use here,
probably)? Or does that get covered incidentally by the installation
instructions?
I'm especially thinking of not confusing a user who sees something
different or doesn't have an "ls", "cd", etc. (Maybe my Windows
command line knowledge is shoddy, though, and those parts just kind of
work close enough for our purposes?)
> +
> +What we'll be doing
> +-------------------
> +
> +Git lets you take snapshots of your code, like a checkpoint in a video
> +game. In this tutorial we're going to explain a very basic Git
> +workflow, which is:
> +
> +1. Create an empty folder
> +2. Start using Git to manage the code in that folder
> +3. Create 2 files and tell Git to save a snapshot of them
> +4. Make changes to one of the files
> +5. Tell Git to take another snapshot
> +6. Repeat steps 4-5 any time you want to update your code
I'm very tempted to nitpick "folder" vs "directory," but I'm not sure
it's worth our time or that of the target audience :) Just note that,
while "git grep folder" finds way more hits than I was expecting, it
seems the primary use in our documentation is in reference to IMAP.
> +We'll also explain how to use Git to put your code on the Internet.
> +
> +Step 1: Make sure Git is installed
> +----------------------------------
> +
> +To do this tutorial, you'll need:
> +
> +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 folder on your computer with code that you want to start managing
> + with Git.
> +
> +You can check if Git is installed by running this in your terminal:
> +
> +------------------------------------------------
> +$ git --version
> +------------------------------------------------
> +
> +[[step_2]]
> +Step 2: Introduce yourself to Git
> +---------------------------------
> +
> +The first time you use Git on a computer, it's a good idea to tell Git
> +your name and public email address. If you don't, you'll get a lot of
> +warnings from Git. To do this, run:
> +
> +------------------------------------------------
> +$ git config --global user.name "Namey McName"
> +$ git config --global user.email you@example.com
> +------------------------------------------------
> +
> +The name and email is so that other people you're collaborating with can
> +know who made the changes. You can set them to anything you want.
> +
> +To check if the name and email have been set, you can run these
> +commands:
> +
> +------------------------------------------------
> +$ git config user.name
> +$ git config user.email
> +------------------------------------------------
Ought we recommend the newer forms (git config set, git config get)?
Or is the idea to remain compatible with older versions, such as the
2.32 I happen to have in /usr/bin on unsupported macOS 12.7.6 from
very old (?) XCode?
> +
> +Set your default branch name to `main`, by running this command.
> +Git is going to change its default branch name to `main` soon, so this
> +sets you up well for the future.
> +
> +------------------------------------------------
> +$ git config --global init.defaultBranch main
> +------------------------------------------------
> +
> +If there's no output, then it succeeded.
> +
> +Step 3: Create an empty folder and 2 files
> +------------------------------------------
> +
> +In your terminal, create an empty folder and change directories 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`
> +
> +------------------------------------------------
> +$ mkdir myproject
> +$ cd myproject
> +------------------------------------------------
I don't know, and I'll probably bias towards what you've already
written over asking for changes, but: does it make things any easier
to read and follow along with if we "git init myproject" instead?
Perhaps this version plants the seed that it's not too late to start
tracking any existing project, though, which is valuable :)
I wonder if you had some rationale for choosing this particular
sequence? Just curious, now.
> +Create 2 files in this directory, so we have something to work with.
> +
> +Make a file called README.md, with these contents:
> +
> +------------------------------------------------
> +We're doing a Git tutorial!
> +We need 2 lines in this file so here's a second one
> +------------------------------------------------
> +
> +And a file called `hello.py`, with these contents:
> +
> +------------------------------------------------
> +print("hello world")
> +------------------------------------------------
> +
> +Save the two files and keep them open in your text editor so you can
> +easily edit them later. The exact contents aren't too important, but
> +we'll use those contents in the example output later.
> +
> +You can check that the files are in the right place by running `ls`,
> +like this:
> +
> +
> +------------------------------------------------
> +$ ls
> +------------------------------------------------
> +
> +The output should be like this:
> +
> +------------------------------------------------
> +hello.py
> +README.md
> +------------------------------------------------
> +
> +Step 4: Create a Git repository
> +-------------------------------
> +
> +A Git repository is a folder which stores snapshots. It's usually a
> +hidden folder called `.git`. Every time you take a snapshot, Git stores
> +a copy of the contents of every file you're tracking.
> +
> +This might feel unbelievable, but Git uses compression so you can easily
> +store tens of thousands of snapshots without using too much disk space.
> +
> +You can create a Git repository for any folder in your computer by
> +running the command `git init`.
> +
> +Run `git init` in the folder you just created, like this:
> +
> +------------------------------------------------
> +$ git init
> +------------------------------------------------
> +
> +Git will reply:
> +
> +------------------------------------------------
> +Initialized empty Git repository in .git/
> +------------------------------------------------
> +
> +You might notice a new hidden folder was created, named `.git`.
> +
> +Step 5: Take your first snapshot
> +--------------------------------
> +
> +Next, we're going to take a snapshot of all the files in the directory
> +and tell Git to store them. Taking a snapshot in Git is a two step
> +process: first you need to run `git add` and then `git commit`.
> +
> +The reason it's a two step process is that sometimes you might not
> +actually want Git to store a snapshot of _all_ the files in a folder.
> +For example, if you have a file full of private personal information
> +called `personal.csv`, and a Python script called `process_data.py`, you
> +might want Git to keep a snapshot of the Python script but not the
> +private data.
> +
> +For now, we're going to store a snapshot of every file in your folder,
> +as well as in every subfolder.
> +
> +The first step of creating a snapshot is to tell Git which files you
> +want to include in the next snapshot using `git add`. To tell Git
> +"include all files", run this command:
> +
> +------------------------------------------------
> +$ git add .
> +------------------------------------------------
> +
> +Next you can create the snapshot using the `git commit` command, like
> +this. The `-m` flag stands for "message", and it lets you set a reminder
> +for your future self of what you were doing. The message ("Initial
> +commit" in this example) can say anything you want.
> +
> +------------------------------------------------
> +$ git commit -m "Initial commit"
> +------------------------------------------------
> +
> +You've now stored the first version of your project in Git! From now on
> +we're going to use the word "commit" instead of "snapshot", since that's
> +the term Git uses.
I know we want to limit scope… but I would love to not accidentally
encourage more use of "-m" for short (often useless?) messages.
Unfortunately, that drags in the can of worms that is editor
configuration. At least we can maybe point to
https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#_editor
and https://git-scm.com/book/en/v2/Appendix-C:-Git-Commands-Setup-and-Config#ch_core_editor
? idk.
> +
> +Step 6: Make a change
> +---------------------
> +
> +Now, let's learn how to make a change to a file and review the change you made.
> +In this example, we'll update the file `README.md`, but you can edit a
> +different file.
> +
> +First open `README.md` in your favourite text editor, make a tiny or
> +silly change, and save it.
> +
> +Next, in the terminal, run the command `git status` to get a summary of
> +what you changed since the last Git commit.
> +
> +------------------------------------------------
> +$ git status
> +------------------------------------------------
> +
> +The output will look something like this:
> +
> +------------------------------------------------
> +On branch main
> +
> +Changes not staged for commit:
> + (use "git add <file>..." to update what will be committed)
> + (use "git restore <file>..." to discard changes in working directory)
> + modified: README.md
> +------------------------------------------------
> +
> +This output says that we've changed `README.md` since the last time
> +we committed.
> +
> +Next, if you want to see the details of how you've changed `README.md`,
> +you can run `git diff`.
> +
> +------------------------------------------------
> +$ git diff
> +------------------------------------------------
> +
> +The output will look something like this:
> +
> +------------------------------------------------
> +diff --git a/README.md b/README.md
> +index 7ebaecb3..5a4ff712 100644
> +--- a/README.md
> ++++ b/README.md
> +@@ -1,2 +1,2 @@
> + Here are some Python scripts!
> ++I hope you like them.
> +------------------------------------------------
> +
> +This output says that we added one line, saying "I hope you like them.".
> +By default Git will show the lines you removed in red, and the lines you
> +added in green.
I would perhaps prefer to focus on the leading sigils (-, +) than the
color, if only because colorblindness can lead to all sorts of
situations with different color setups in the terminal's palette or
even (probably not our target audience) Git configuration. We could
probably mention that Git shows added and removed lines in *different*
colors without being too concerned with which colors those are? (That
avoids having to twist our words like "your terminal palette's green
and red" or w/e.)
> +
> +Step 7: Make another commit (easy way)
> +--------------------------------------
> +
> +Now let's tell Git to save the new version of `README.md` by making
> +another commit! To tell Git to snapshot all files that Git is tracking
> +and commit them, run this command:
> +
> +------------------------------------------------
> +$ git commit -am "Update README"
> +------------------------------------------------
> +
> +This is similar to the two step process in Step 4 where we used `git
> +add` and `git commit` to make a commit, but with a shortcut that lets
> +you do both in just one command. The `-a` stands for "all".
> +
> +Step 7b: Make another commit (longer way)
> +-----------------------------------------
> +
> +`git commit -am` is a fast way to snapshot all the files that Git is
> +tracking. But if you want Git to ignore changes to certain files, you
> +can instead do a 2-step process like in Step 4 where first you run `git
> +add` for every file that's been changed and that you want to include in
> +the next commit, like this:
> +
> +------------------------------------------------
> +$ git add README.md
> +------------------------------------------------
> +
> +and then run `git commit` (without the `-a`), like this:
> +
> +------------------------------------------------
> +$ git commit -m "Update README"
> +------------------------------------------------
> +
> +Step 8: Make a change and throw it away
> +---------------------------------------
> +
> +One of the most useful things about Git is that it lets you safely
> +experiment: you never need to be scared to change your code because you
> +can always go back to the old version.
> +
> +Before starting to experiment, run `git status` to check the current
> +state of your Git repository:
> +
> +------------------------------------------------
> +$ git status
> +On branch main
> +
> +nothing to commit, working tree clean
> +------------------------------------------------
> +
> +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
> +time, you should see a message like this:
> +
> +------------------------------------------------
> +$ git status
> +On branch main
> +
> +Changes not staged for commit:
> + (use "git add <file>..." to update what will be committed)
> + (use "git restore <file>..." to discard changes in working directory)
> + modified: README.md
> +------------------------------------------------
> +
> +This tells us that `README.md` has been changed since the last commit.
> +But we don't actually want this change, so let's undo it! We can restore
> +`README.md` back to how it was at the most recent commit using the `git
> +restore` command.
> +
> +**WARNING**: `git restore` can't be reversed! Any time you run it it's
> +important to be absolutely sure that you're okay with throwing away your
> +changes since the last commit.
> +
> +------------------------------------------------
> +$ git restore README.md
> +------------------------------------------------
> +
> +Now open `README.md` again. You should see that your changes have been undone.
> +
> +You can stop here!
> +------------------
> +
> +The commands we've learned so far (`git init`, `git add`, `git commit`,
> +`git diff`, `git status`, and `git restore`) are enough to get a lot out
> +of Git on their own.
> +
> +With these commands, you can keep copies of past versions of your code
> +on your computer and safely experiment with big changes to your code.
> +
> +When using Git this way, all of your code just lives on your computer.
> +But if you want to put your code on the Internet so that other people
> +can use it or back it up, then you'll need to learn about one more
> +command: `git push`.
> +
> +The rest of this tutorial is about how to upload your code to a Git
> +repository on the Internet. The high level process is:
> +
> +1. Create an account on the Git host
> +2. Configure Git so that it can login to the Git host to make changes
> +3. Run `git push origin main` to upload your code
> +
> +Navigating the Git host's UI can be tricky, and it's hard for us to
> +give you exact directions because the UIs change a lot.
> +
> +Step 9: Create an account on a Git host
> +---------------------------------------
> +
> +To put your code on the Internet, you need it to be hosted somewhere.
> +The easiest way to do this is to sign up with a Git host. There's a list
> +of Git hosts (many of them offer free accounts) at
> +https://git-scm.com/tools/hosting. GitHub and GitLab are two popular hosts.
> +
> +If you're comfortable running a server, there are other ways to host
> +a Git repository on the internet, like connecting through SSH or open
> +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
> +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
> +-------------------------------------------
> +
> +`ssh-keygen` will ask you for some details.
> +The easiest way to do this is to just press Enter at every prompt until
> +it's done.
> +
> +NOTE: All of the advice about how to use SSH in this tutorial is aimed
> +at getting it to work as quickly as possible. Setting up SSH in a secure
> +way is very far outside the scope of this tutorial. If you have a
> +security team in your organization, they might have very different
> +opinions about the appropriate way to configure authentication with Git.
> +
> +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").
> +
> +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 12: Create an empty Git repository on the Git host
> +-------------------------------------------------------
> +
> +Go to the Git host's website and create a new Git repository.
> +
> +**WARNING**: If you create a public repository and push your repository
> +to it, then your name and email address, as well as the contents of
> +any files you committed and every previous version of those files, will
> +be on the public internet. Some Git hosts have the option to create
> +a private repository instead, to keep your information private.
> +
> +Step 13: Find the address of the repository
> +-------------------------------------------
> +
> +Now, find the address of the repository on your Git host. It should look
> +something like this:
> +
> +-------------------------------------------
> +git@git.example.com:username/repo.git
> +-------------------------------------------
> +
> +(where `example.com`, `username` and `repo` will be replaced with the
> +actual values).
> +
> +If you can only find an address starting with `https://`, then
> +you can often translate it to the SSH format by replacing `https://`
> +with `git@` and replacing the `/` after the domain name with an `:`.
> +Here's how:
> +
> +-------------------------------------------
> +https://git.example.com/username/repo
> +^^^^^^^^ ^
> +replace with "git@" replace with ":"
> +-------------------------------------------
This is, of course, forge- and remote- dependent :) but I think it's
*probably* ok for the tutorial.
When you mentioned HTTPS-to-SSH translation, I was thinking of the
config-based URL rewrite mechanism, aha! I definitely don't think we
should go there ;)
> +
> +Step 14: push your changes
> +--------------------------
> +
> +Finally, we're ready to send the information in your local Git repository
> +to the one on the internet!
> +
> +First, tell Git about the other repository by running `git remote add`
> +in your terminal
> +(replace `git@example.com:username/repo.git` with the actual address):
> +
> +-------------------------------------------
> +$ git remote add origin git@example.com:username/repo.git
> +-------------------------------------------
> +
> +This tells Git to save the URL `git@example.com:username/repo.git` in
> +your Git repository's configuration under the name `origin`, so that you
> +can use it later. If you make a mistake while doing this, you can run
> +`git remote remove origin` and try again.
> +
> +Then tell Git to send the information, with `git push`
> +(if this doesn't work, read the "Troubleshooting `git push`" section for advice!):
> +
> +-------------------------------------------
> +$ git push -u origin main
> +-------------------------------------------
> +
> +`origin` refers to the URL we just added (`git@example.com:username/repo.git`),
> +and `main` is the name of your current Git branch. You can use any name
> +(not just `origin`), but using `origin` often makes things easier
> +because it's the default for `git push` and `git pull`.
> +We haven't covered branches yet, but `main` is the default branch name.
I'm not sure if we should recommend "-u" without being able to explain
what it does, and… well… you and I have discussed how that's difficult
:)
Doesn't the tutorial's recipe of always using "git push origin main"
work just fine? And if we later introduce pull and other
branch-/remote-stuff that cares about upstreams, we can mention this
shorthand then?
> +
> +Any time you want to set up a new repository, you can repeat steps
> +11-13, with one exception: you only need to pass `-u` the first time
> +you push. Afterwards you can just run the command:
> +
> +-------------------------------------------
> +$ git push origin main
> +-------------------------------------------
> +
> +It should output something like this:
> +
> +-------------------------------------------
> +To example.com:example_username/example
> + * [new branch] main -> main
> +-------------------------------------------
> +
> +Troubleshooting `git push`
> +--------------------------
> +
> +There are 3 main errors you might run into when running `git push origin main`.
> +Getting errors when running `git push` is actually a big part of using
> +Git, so congratulations! If you get to this part of the tutorial, you
> +get a little bonus experience in debugging.
> +
> +Here's a guide to why they're happening and how to fix them.
> +
> +**Problem 1**: You pushed to `main`, but your branch actually isn't called `main`
> +
> +Here's the error:
> +```
> +$ git push origin main
> +error: src refspec main does not match any
> +```
> +
> +This might happen if you didn't set `init.defaultBranch` to `main` in
> +<<step_2,Step 2>>.
> +
> +If you want to check the name of your current branch, you can run `git
> +status`. For example, in this output, the current branch is "master".
> +
> +-------------------------------------------
> +$ git status
> +On branch master
> +
> +...
> +-------------------------------------------
> +
> +To push your branch, you have a few options:
> +
> +* rename your branch to `main`, by running `git branch -m main`
> + and then run `git push origin main`
> +* run `git push origin master`
> + (where `master` is the name of your actual current branch)
> +
> +**Problem 2: SSH error**
> +
> +Here's the error:
> +
> +-----
> +$ git push origin main
> +The authenticity of host 'github.com (140.82.116.3)' can't be established.
> +ED25519 key fingerprint is: SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU
> +This key is not known by any other names.
> +Are you sure you want to continue connecting (yes/no/[fingerprint])?
> +-----
> +
> +Git uses SSH to connect during `git push`, and this message happens when
> +SSH connects to a new site that you haven't connected to before.
> +
> +The easiest way to handle this is to type "yes" and press Enter.
> +
> +**Problem 3: the repository already exists**
> +
> +Here's the error:
> +
> +---------------------
> +$ git push origin main
> +! [rejected] main -> main (fetch first)
> +error: failed to push some refs to 'example.com:example/example.git'
> +hint: Updates were rejected because the remote contains work that you do not
> +hint: have locally.
> +---------------------
> +
> +If you see an error like this, it means that when you created the
> +repository on your Git host, it created a repository with a file in it
> +to try to help you out. (that's the "work that you do not have locally"
> +in the error message)
> +
> +You can fix this either by deleting the repository and recreating it, or
> +by running:
> +
> +---------------------
> +$ git push --force origin main
> +---------------------
> +
> +**WARNING**: In general it's quite dangerous to use `--force` because
> +it can erase work on the online repository in a way that's difficult to
> +recover. But if you know for sure that you just created the repository 2
> +minutes ago and there's nothing in it, then it's okay.
> +
> +MORE USEFUL GIT COMMANDS
> +------------------------
> +
> +* To tell Git to "un-add" a file that you added by accident, run
> + `git rm --cached FILENAME`
> +
> +SEE ALSO
> +--------
> +linkgit:git-help[1],
> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite
> --
> gitgitgadget
Overall I think this is excellent (and I wish bottom-post replies
encouraged saying this up front, hm).
Thanks!
--
D. Ben Knoble |
|
The pull request has 33 commits. The max allowed is 30. Please split the patch series into multiple pull requests. Also consider squashing related commits. |
jvns
force-pushed
the
git-tutorial
branch
4 times, most recently
from
October 19, 2026 14:16
d6cd912 to
c2f6b88
Compare
|
This patch series is no longer integrated into seen. |
|
This patch series was integrated into seen via git@5acbbbe. |
|
Ben Knoble wrote on the Git mailing list (how to reply to this email): > Le 23 oct. 2026 à 11:17, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
>
> 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)
I noticed some discussion in Discord about the main text being out of date,
but while the appendix makes copious references to editors
that have fallen out of style I think it also covers common cases
like VS Code and so on.
> * 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
The range-diff below looks fine to me! A few small nits, but I don’t
want to hold things up.
> 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
Personally, I’d drop « extremely » here to avoid casting a judgement?
> ++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.
Perhaps « bottom-left »; they aren’t in the rows with text,
for example.
> ++
> ++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`
I never know if I’m over-indexing on this, but: perhaps
« press the Escape key, type …, and press Enter »? One probably
does not want to type the word Escape ;)
Ideally we’d recommend :cquit!, too, to exit with an error
in case the user accidentally edited the buffer and managed to write it,
in which case they may create a commit and the recovery may be confusing.
But POSIX doesn’t require that of vi/ex even though most distros
ship Vim as the implementation. So :q! will have to do.
> ++2. Run `git config --global core.editor YOUR_PREFERRED_EDITOR`
This is probably ok for now. Long term I encourage folks to set
EDITOR and/or VISUAL environment variables, so all
programs know what to do, but shell configuration is way
off-topic here :)
> ++ 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 |
|
This branch is now known as |
|
There was a status update in the "Cooking" section about the branch The beginner's tutorial in 'gittutorial.adoc' has been rewritten to focus on a minimal set of commands needed to create a repository, make commits, and push to a remote host, optimizing for a quick one-hour learning experience. Needs review. cf. <F2555C10-8453-4196-9D07-02870D19199D@gmail.com> source: <pull.2248.v3.git.1792768625.gitgitgadget@gmail.com> |
|
Richard Kerry wrote on the Git mailing list (how to reply to this email) regarding 41dca2e (outdated): Hi Julia, Team,
There was a request earlier for notes from Windows Git users, so as I am one I thought I might respond a little.
I use Git mostly via a GUI app. I do understand that documentation for Git proper needs to treat it as command-line as all the GUIs are a bit different. I think they all work via the CLI version and all that I use do always show the commands, so I quite understand that documentation needs to be done like that.
However....
Windows users don't use vim (or vi).
Windows users don't use ssh.
I'm sure neither of those are completely true, so please no-one write in and say that I'm wrong, but I think a lot of Windows Git users won't do so, and will feel such mentions are not aimed at them and may take it that the whole document isn't either.
I'm sure I've read somewhere that ssh is a nightmare to set up on Windows, so a first-class mention of it may put off Windows users. It might perhaps get a note that it's for Linux/Unix/etc users only (or only-ish). Anyway, I've been developing on Windows for about 30 years and using Git for about eight, and never needed ssh for anything. Https is all that I've used for GitHub and BitBucket, which you might consider likely to be the most common servers users might see. And bearing in mind that GitHub has on-prem versions that may be found in corporate settings. I'm not sure how easy it is to set up a local Git server by other means as I've never really tried.
Vim I think is very uncommon on Windows. The only editor that is universal is NotePad, but I don't think that would be used much for serious development. I use versions of Visual Studio but Visual Studio Code (no relation) may be more common nowadays. For general editing I may use emacs for historical reasons, but I suspect that's nearly as rare on Windows as vim. Something like NotePad++ would be better. But then again, it isn't universal.
In short, if it mentions of someone using ssh and vim, I immediately think they are a Linux user, and I may tend to skip those parts of an article, or even assume the whole thing is not aimed at me.
Kind regards,
Richard Kerry
BNCS Engineer - Media Competency Centre
MidCity Place, 71 High Holborn - London WC1V 6EA - UK
atos.ai
> -----Original Message-----
> From: Julia Evans <julia@jvns.ca>
> Sent: 20 October 2026 19:23
> To: Junio C Hamano <gitster@pobox.com>
> Cc: Julia Evans via GitGitGadget <gitgitgadget@gmail.com>; git@vger.kernel.org
> Subject: Re: [PATCH 2/2] doc: add new Git tutorial for beginners
>
> Caution: External email. Do not open attachments or click links, unless this email
> comes from a known sender and you know the content is safe.
>
>
> >
> >> +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 '-'.
>
> I meant to reply to this one. I wonder if it would be better to update all the
> headings to use a different form, like this, because it's easy to accidentally get the
> number of `-` characters wrong when editing a heading.
>
> == Step 10: Create an SSH key (if needed)
>
> I don't feel strongly about that though, happy to stay consistent with how other
> pages do it.
Atos is a trading name used by the Atos group. The trading entity is registered in England and Wales: Atos IT Services UK Limited (registered number 01245534). The registered office is located at: Second Floor, MidCity Place, 71 High Holborn, London, WC1V 6EA. The VAT No. is: GB232327983. This e-mail and the documents attached are confidential and intended solely for the addressee and may contain confidential or privileged information. If you receive this e-mail in error, you are not authorised to copy, disclose, use, or retain it. Please notify the sender immediately and delete this email from your systems. As emails may be intercepted, amended, or lost, they are not secure. Atos therefore can accept no liability for any errors or their content. Although Atos endeavours to maintain a virus-free network, we do not warrant that this transmission is virus-free and can accept no liability for any damages resulting from any virus transmitted. The risks are deemed to be accepted by everyone who communicates with Atos by email. |
|
User |
The next commit replaces it with a new tutorial. Do this as a remove/add instead of just replacing the file in a single commit to make the patches easier to read on the mailing list, since the existing content isn't being reused. Signed-off-by: Julia Evans <julia@jvns.ca>
|
"Julia Evans" wrote on the Git mailing list (how to reply to this email) regarding 41dca2e (outdated): On Mon, Oct 26, 2026, at 12:03 PM, Richard Kerry wrote:
> Hi Julia, Team,
>
> There was a request earlier for notes from Windows Git users, so as I
> am one I thought I might respond a little.
I really appreciate this, it's (obviously) very important that the tutorial work
well on Windows, and as you can probably tell when reading it, I haven't used
Windows in a very long time. But that shortcoming of mine shouldn't mean that
the tutorial deprioritizes Windows users' point of view :)
Also ccing Johannes.
> I use Git mostly via a GUI app. I do understand that documentation for
> Git proper needs to treat it as command-line as all the GUIs are a bit
> different. I think they all work via the CLI version and all that I
> use do always show the commands, so I quite understand that
> documentation needs to be done like that.
>
> However....
>
> Windows users don't use vim (or vi).
Re vim: I'd love any ideas for how to make it more clear that using vim
isn't required in any way to use Git on Windows.
My understanding is that Git for Windows asks you to configure an editor
when installing Git, so maybe we could say something like this:
By default, Git uses the `vi` text editor, which is extremely difficult
to use if you're not used to it. On Windows, Git for Windows asks you to
configure a text editor during the install to avoid this problem.
And of course it's not just Windows users who are not comfortable
with vim, there are many Mac and Linux users who don't know it either.
I'd imagine only a small minority of Git beginners in 2026 are comfortable
using vim.
> Windows users don't use ssh.
> I'm sure neither of those are completely true, so please no-one write
> in and say that I'm wrong, but I think a lot of Windows Git users won't
> do so, and will feel such mentions are not aimed at them and may take
> it that the whole document isn't either.
>
> I'm sure I've read somewhere that ssh is a nightmare to set up on
> Windows, so a first-class mention of it may put off Windows users. It
> might perhaps get a note that it's for Linux/Unix/etc users only (or
> only-ish). Anyway, I've been developing on Windows for about 30 years
> and using Git for about eight, and never needed ssh for anything.
> Https is all that I've used for GitHub and BitBucket, which you might
> consider likely to be the most common servers users might see. And
> bearing in mind that GitHub has on-prem versions that may be found in
> corporate settings. I'm not sure how easy it is to set up a local Git
> server by other means as I've never really tried.
I think the idea of giving HTTPS instructions is interesting.
I don't know if it's possible to give vendor-neutral directions for how to set
up Git with HTTPS, but if it is I'd be happy to give it a try. I'd love any
pointers or suggestions for how to do this.
> Vim I think is very uncommon on Windows. The only editor that is
> universal is NotePad, but I don't think that would be used much for
> serious development. I use versions of Visual Studio but Visual Studio
> Code (no relation) may be more common nowadays. For general editing I
> may use emacs for historical reasons, but I suspect that's nearly as
> rare on Windows as vim. Something like NotePad++ would be better. But
> then again, it isn't universal.
>
> In short, if it mentions of someone using ssh and vim, I immediately
> think they are a Linux user, and I may tend to skip those parts of an
> article, or even assume the whole thing is not aimed at me.
>
This makes sense to me, and I agree it's important to be careful about
how we talk about SSH and vim for the reasons you say.
I think a lot about how to make sure that the Git documentation is
trustworthy and credible, and when we suggest using tools that are
unfamiliar or not commonly used, it reduces credibility and makes it
more likely that people will leave to find information somewhere else.
>
> Kind regards,
>
> Richard Kerry
> BNCS Engineer - Media Competency Centre
> MidCity Place, 71 High Holborn - London WC1V 6EA - UK
> atos.ai |
|
"Julia Evans" wrote on the Git mailing list (how to reply to this email) regarding 41dca2e (outdated): >> I'm sure I've read somewhere that ssh is a nightmare to set up on
>> Windows, so a first-class mention of it may put off Windows users. It
>> might perhaps get a note that it's for Linux/Unix/etc users only (or
>> only-ish). Anyway, I've been developing on Windows for about 30 years
>> and using Git for about eight, and never needed ssh for anything.
>> Https is all that I've used for GitHub and BitBucket, which you might
>> consider likely to be the most common servers users might see. And
>> bearing in mind that GitHub has on-prem versions that may be found in
>> corporate settings. I'm not sure how easy it is to set up a local Git
>> server by other means as I've never really tried.
>
> I think the idea of giving HTTPS instructions is interesting.
> I don't know if it's possible to give vendor-neutral directions for how to set
> up Git with HTTPS, but if it is I'd be happy to give it a try. I'd love any
> pointers or suggestions for how to do this.
I just did some research and I found out that Git for Windows comes with
Git Credential Manager, which pops up a little dialog the first time you run
`git push` asking you to log in to your Git host. It looks like it works on
most popular Git hosting services, and if anybody is running their
own Git server that only works with SSH auth then they can follow the SSH
directions.
So I think that we can separate the authentication setup into the Windows
section (where we tell people to use GCM) and the Mac/Linux section
(where we tell people to use SSH). |
|
Junio C Hamano wrote on the Git mailing list (how to reply to this email) regarding 41dca2e (outdated): "Julia Evans" <julia@jvns.ca> writes:
>> In short, if it mentions of someone using ssh and vim, I immediately
>> think they are a Linux user, and I may tend to skip those parts of an
>> article, or even assume the whole thing is not aimed at me.
>
> This makes sense to me, and I agree it's important to be careful about
> how we talk about SSH and vim for the reasons you say.
>
> I think a lot about how to make sure that the Git documentation is
> trustworthy and credible, and when we suggest using tools that are
> unfamiliar or not commonly used, it reduces credibility and makes it
> more likely that people will leave to find information somewhere else.
OK, so shall I mark the topic on hold until you decide if I should
expect a reroll or we'll address the above in follow-up changes in
other topics in future?
Thanks. |
|
"Julia Evans" wrote on the Git mailing list (how to reply to this email) regarding 41dca2e (outdated): On Mon, Oct 26, 2026, at 4:17 PM, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
>>> In short, if it mentions of someone using ssh and vim, I immediately
>>> think they are a Linux user, and I may tend to skip those parts of an
>>> article, or even assume the whole thing is not aimed at me.
>>
>> This makes sense to me, and I agree it's important to be careful about
>> how we talk about SSH and vim for the reasons you say.
>>
>> I think a lot about how to make sure that the Git documentation is
>> trustworthy and credible, and when we suggest using tools that are
>> unfamiliar or not commonly used, it reduces credibility and makes it
>> more likely that people will leave to find information somewhere else.
>
> OK, so shall I mark the topic on hold until you decide if I should
> expect a reroll or we'll address the above in follow-up changes in
> other topics in future?
I'll aim to send a new version this week. |
|
Junio C Hamano wrote on the Git mailing list (how to reply to this email) regarding 41dca2e (outdated): "Julia Evans" <julia@jvns.ca> writes:
>> OK, so shall I mark the topic on hold until you decide if I should
>> expect a reroll or we'll address the above in follow-up changes in
>> other topics in future?
>
> I'll aim to send a new version this week.
Thanks. Marked as "Expecting a reroll." |
|
This patch series is no longer integrated into seen. |
|
"Julia Evans" wrote on the Git mailing list (how to reply to this email): On Fri, Oct 23, 2026, at 2:01 PM, Ben Knoble wrote:
>> Le 23 oct. 2026 à 11:17, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
>>
>> 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)
>
> I noticed some discussion in Discord about the main text being out of date,
> but while the appendix makes copious references to editors
> that have fallen out of style I think it also covers common cases
> like VS Code and so on.
>
>> * 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
>
> The range-diff below looks fine to me! A few small nits, but I don’t
> want to hold things up.
>
>> 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
>
> Personally, I’d drop « extremely » here to avoid casting a judgement?
The goal isn't to judge vim (I love vim!), it's to make sure people who aren't
familiar with it know that it's not a good idea to try to figure out how to use it
in the middle of a tutorial on how to use Git.
It's almost impossible for me to imagine someone successfully learning vim
when they're unexpectedly put into it for the first time.
>> ++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.
>
> Perhaps « bottom-left »; they aren’t in the rows with text,
> for example.
Good idea, will do.
>> ++
>> ++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`
>
> I never know if I’m over-indexing on this, but: perhaps
> « press the Escape key, type …, and press Enter »? One probably
> does not want to type the word Escape ;)
Good idea, will do.
> Ideally we’d recommend :cquit!, too, to exit with an error
> in case the user accidentally edited the buffer and managed to write it,
> in which case they may create a commit and the recovery may be confusing.
> But POSIX doesn’t require that of vi/ex even though most distros
> ship Vim as the implementation. So :q! will have to do.
>
>> ++2. Run `git config --global core.editor YOUR_PREFERRED_EDITOR`
>
> This is probably ok for now. Long term I encourage folks to set
> EDITOR and/or VISUAL environment variables, so all
> programs know what to do, but shell configuration is way
> off-topic here :)
Yeah. It also depends on whether the user is planning to use a terminal
editor at all, I think some folks will choose to use their IDE integration to
work with Git and so setting EDITOR might never become relevant in
that case. |
|
Ben Knoble wrote on the Git mailing list (how to reply to this email): > Le 27 oct. 2026 à 10:30, Julia Evans <julia@jvns.ca> a écrit :
>
>
>
> On Fri, Oct 23, 2026, at 2:01 PM, Ben Knoble wrote:
>>>> Le 23 oct. 2026 à 11:17, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
>>>
>>> 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)
>>
>> I noticed some discussion in Discord about the main text being out of date,
>> but while the appendix makes copious references to editors
>> that have fallen out of style I think it also covers common cases
>> like VS Code and so on.
;) long emails?
>>> ++
>>> ++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
>>
>> Personally, I’d drop « extremely » here to avoid casting a judgement?
>
> The goal isn't to judge vim (I love vim!), it's to make sure people who aren't
> familiar with it know that it's not a good idea to try to figure out how to use it
> in the middle of a tutorial on how to use Git.
>
> It's almost impossible for me to imagine someone successfully learning vim
> when they're unexpectedly put into it for the first time.
I too love Vim, and I agree. (Well, I sort of did learn both at
the same time, but I had a lot of free time as a first-semester
freshman in college…).
Anyway, I think since the goal is not to judge, I’d still consider dropping
« extremely », but it’s your call!
>>> ++2. Run `git config --global core.editor YOUR_PREFERRED_EDITOR`
>>
>> This is probably ok for now. Long term I encourage folks to set
>> EDITOR and/or VISUAL environment variables, so all
>> programs know what to do, but shell configuration is way
>> off-topic here :)
>
> Yeah. It also depends on whether the user is planning to use a terminal
> editor at all, I think some folks will choose to use their IDE integration to
> work with Git and so setting EDITOR might never become relevant in
> that case.
Well, if they use their IDE’s integrated terminal and run a command
that looks at either variable… ;) Although I wonder if some set
those variables in such terminals automatically?
Regardless, I’ll let this one go as it’s off-topic as I said ‘:D |
|
This patch series was integrated into seen via git@41bc71a. |
|
Julia Evans wrote on the Git mailing list (how to reply to this email): > On Oct 27, 2026, at 11:19 AM, Ben Knoble <ben.knoble@gmail.com> wrote:
>
>>
>> Le 27 oct. 2026 à 10:30, Julia Evans <julia@jvns.ca> a écrit :
>>
>>
>>
>> On Fri, Oct 23, 2026, at 2:01 PM, Ben Knoble wrote:
>>>>> Le 23 oct. 2026 à 11:17, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
>>>>
>>>> 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)
>>>
>>> I noticed some discussion in Discord about the main text being out of date,
>>> but while the appendix makes copious references to editors
>>> that have fallen out of style I think it also covers common cases
>>> like VS Code and so on.
Yeah I now see that’s a great list, I’ll add a link. I wonder if at some point in the
future it would make sense to manage this list in Git (like with merge tools)
but that’s out of scope :)
> ;) long emails?
Yes, I really need to start using Apple Mail more consistently.
The Fastmail web UI I’ve been using really doesn’t work for these emails :)
>>>> ++
>>>> ++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
>>>
>>> Personally, I’d drop « extremely » here to avoid casting a judgement?
>>
>> The goal isn't to judge vim (I love vim!), it's to make sure people who aren't
>> familiar with it know that it's not a good idea to try to figure out how to use it
>> in the middle of a tutorial on how to use Git.
>>
>> It's almost impossible for me to imagine someone successfully learning vim
>> when they're unexpectedly put into it for the first time.
>
> I too love Vim, and I agree. (Well, I sort of did learn both at
> the same time, but I had a lot of free time as a first-semester
> freshman in college…).
>
> Anyway, I think since the goal is not to judge, I’d still consider dropping
> « extremely », but it’s your call!
>
I’ll think about it! Maybe we can briefly explain what it is about vim that makes it so
difficult (like "Some signs that you're trapped in `vi`: suddenly typing doesn’t work
anymore…”) and take a more “show don’t tell” approach.
>>>> ++2. Run `git config --global core.editor YOUR_PREFERRED_EDITOR`
>>>
>>> This is probably ok for now. Long term I encourage folks to set
>>> EDITOR and/or VISUAL environment variables, so all
>>> programs know what to do, but shell configuration is way
>>> off-topic here :)
>>
>> Yeah. It also depends on whether the user is planning to use a terminal
>> editor at all, I think some folks will choose to use their IDE integration to
>> work with Git and so setting EDITOR might never become relevant in
>> that case.
>
> Well, if they use their IDE’s integrated terminal and run a command
> that looks at either variable… ;) Although I wonder if some set
> those variables in such terminals automatically?
>
> Regardless, I’ll let this one go as it’s off-topic as I said ‘:D
|
Introduce Git in two parts: Steps 1-7: Create an empty repo & make 2 commits (`git init`, `git add`, `git commit`, `git status`, `git diff`) Steps 8-12: Push the repo to a remote host like GitHub or GitLab (`git remote add`, `git push`) 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 to be a good balance. - Have users start with an empty repository instead of an existing project, because many of the testers did not have an existing project to test, or were scared of using an existing project. - Add a troubleshooting section, since in the testing some users got extremely stuck (for 4+ hours) on minor issues like needing to say "yes" when SSHing to a new host. - Don't explain branches, because explaining branches and collaboration is complicated and deserves its own tutorial. Instead just tell users we're not going to explain them in this document. - Tell users to set their default branch to `main`, because many Git hosts use it as their default branch and it really simplifies things. - Keep it as vendor neutral as possible, while acknowledging the reality that Git hosting services like GitHub, GitLab, etc are extremely popular. Do this by creating the repo locally and then optionally pushing it later. - Use SSH for authentication, 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), and giving some instructions for how to translate an HTTPS URL to an SSH URL. - Use Git Credential Manager for authentication on Windows, since it's simpler, SSH auth is a very "unixy" thing to do, and it comes with Git for Windows - 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>
Author
|
/submit |
|
Submitted as pull.2248.v4.git.1793198687.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
This patch series is no longer integrated into seen. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
2.23.0, whengit switchwas introduced, since the next part of the tutorial on branches will usegit switchvi, 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)Helped-by: Ben ...cat ~/.ssh/whatever.pubto 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)ed25519.pub(thanks to Junio)git status== DESCRIPTION(thanks to Junio)--set-upstreamdoes (thanks to Ben)non-changes in v3:
git config setsince the tutorial claims to be compatible with Git 2.23.0git initinstead ofgit init myprojectso that folks can use the same process when setting up Git in an existing projectchanges in v4:
Make the instructions more Windows-friendly (thanks to Richard Kerry), by:
Also:
non-changes in v4:
cc: "D. Ben Knoble" ben.knoble@gmail.com
cc: Tuomas Ahola taahol@utu.fi
cc: Richard Kerry richard.kerry@atos.ai