From: Julia Evans via GitGitGadget Date: Tue, 06 Oct 2026 19:37:02 GMT Subject: [PATCH 2/2] doc: add new Git tutorial for beginners Message-ID: <41dca2e8e0c5fadb8ad9ed8707029356e56cc540.1791315422.git.gitgitgadget@gmail.com> In-Reply-To: From: Julia Evans 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 --- 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. + +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 + +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 +------------------------------------------------ + +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 +------------------------------------------------ + +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. + +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 ..." to update what will be committed) + (use "git restore ..." 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. + +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 ..." to update what will be committed) + (use "git restore ..." 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 ":" +------------------------------------------- + +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. + +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 +<>. + +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