gittutorial(7) Manual Page

Git is a program that lets you collaborate with others on code, back up your code, roll back to an earlier version of your project, track how your project has changed over time, and much more.

This tutorial explains how to create a new Git project, make changes to it, and upload the project to the Internet. It usually takes less than an hour if you have a little previous experience with Git, and 1-2 hours if not.

We’ll show you how to use the commands git commit, git add, git diff, git status, and git push.

Git lets you take snapshots of your code, like a checkpoint in a video game. These snapshots are called "commits". Which files to save in a commit is up to you.

When Git stores a commit, it stores a copy of every file in the commit in a database in a folder called .git. This is called a "Git repository".

In this tutorial we’re going to show you how to:

We’ll also explain how to use Git to put your code on the Internet.

Git is a command line program, but there are many graphical interfaces for Git built by the community. Your text editor might even have a built-in Git integration.

In this tutorial, we’ll give instructions for using Git from the command line. We can’t give you instructions for how to do it in your graphical interface because there are so many of them.

You can always switch back and forth between using the command line and a graphical interface at any time.

To do this tutorial, you’ll need:

You can check if Git is installed by running this in your terminal:

It should output something like this:

The exact version isn’t too important: this tutorial is designed to work with any version of Git after 2.23.0.

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:

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. They should display your name and email:

Next, configure Git to set the default branch name to main (instead of master) by running this command. We can’t explain what a branch is yet, but Git is going to make main the default soon, and setting this avoids some extremely annoying problems in Step 14.

If there’s no output, then it succeeded.

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:

Next, using your text editor, create a file in this folder, so we have something to work with.

Make a file called README.md, with these contents:

Save README.md and keep it open in your text editor so you can easily edit it later. The exact contents aren’t too important, but we’ll use those contents in the example output later.

You can check that the file is in the right place by running ls, like this:

The output should look like this:

A Git repository lets you save snapshots of your code. Every time you make a snapshot, Git stores a copy of the contents of every file in the snapshot.

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 will reply:

You might notice a new hidden folder was created, named .git. You don’t need to use this folder directly in any way, but it’s where your commits will be stored.

Next, we’re going to take a snapshot of all the files in the directory and tell Git to store them. Git calls these snapshots "commits". Making a commit 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 commit with all the files in a folder. For example, if you’re compiling your program to a binary, you might want Git to put the program’s source code in your commit but not compiled binary. You can also use a .gitignore file to help with this.

For now, we’re going to store a commit with every file in your folder, as well as in every subfolder.

The first step of making a commit is to tell Git which files you want to include in the commit using git add. To tell Git "include all files", run this command:

To check if it succeeded, you can run git status. The output should look like this:

Next you can create the commit 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.

The output should look like this:

You’ve now stored the first version of your project in Git!

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.

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. In our example, we’ll edit the first line to add more exclamation marks:

Next, in the terminal, run the command git status to get a summary of what you changed since the last Git commit.

The output will look something like this:

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.

The output will look something like this:

This output says that we deleted one line (We're doing a Git tutorial!) and added one line (We're doing a Git tutorial!!!!). By default Git will show the lines you removed in red, and the lines you added in green. Removed lines start with a minus - and added lines start with a plus +.

Now that we’ve changed README.md, let’s make another commit. We’re going to follow the same steps as before when we made our first commit.

First, tell Git that we want to include the new version of README.md in the next commit:

and then run git commit, like this:

The output should look like this:

This says that the new commit is the same as the previous commit, except that we changed 1 line of 1 file.

Instead of running the two commands in Step 7a above, you could also run this command as a shortcut. It will:

The -a stands for "all".

Now let’s talk about a term you’ll see in the git status output: "untracked files".

First create a new file called example.txt. It can be empty.

Then run the command git status. You should see this output:

This has a list of "untracked files". An untracked file is a file which was not part of the latest commit. By default Git will ignore these files.

If you want to commit an untracked file, you can add it like this:

Then you can run git commit to commit it (though see the warning in the next section!).

If you run git commit without any arguments, Git will open a text editor in the terminal for you to use to edit your commit message. This lets you write a longer commit message with more details. By default, Git uses the vi text editor, which is extremely difficult to use if you’re not used to it. On Windows, the Git installer asks you to set your text editor during the install to avoid this problem.

Some signs that you’re trapped in vi: suddenly typing doesn’t work anymore, and there are tilde ~ characters on the bottom left of the screen.

If Git opens vi and you’d rather use a different editor, you can handle it like this:

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.

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:

This "working tree clean" message means that there haven’t been any changes since your last commit.

Now make a change to README.md, and run git status again. Like last time, you should see a message like this:

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.

Now open README.md again. You should see that your changes have been undone.

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:

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. There’s a rich tradition of people learning Git from their "Git friend" who already knows Git, and if you have one of those it might be useful to ask them if you get stuck. There are many ways to do things in Git, so they might suggest a slightly different way. There’s also a troubleshooting guide at the end with the most common issues folks have run into while doing this tutorial.

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.

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.

On Windows, you can skip this step and the next one because Git for Windows comes with Git Credential Manager to handle logging in.

If you don’t already have an SSH key, you’ll need to create one. You can check if you already have an SSH key by running:

If you don’t already have an SSH key, run:

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.

First, find your SSH key like this:

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"):

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.

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.

Go to the Git host’s website and create a new Git repository. If there’s an option to "create a README.md", "add a license", or something similar, make sure to say no to all of them.

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.

Now, find the address of the repository on your Git host.

If you followed the Mac/Linux instructions to set up an SSH key, look for an "SSH" address like this:

If you’re on Windows, look for an "HTTPS" address like this:

(where example.com, username and repo will be replaced with the actual values).

If you can only find an address starting with https:// and you need an SSH address 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:

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 address from Step 13):

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!):

On Windows, this should pop up a dialog from Git Credential Manager asking you to log in to the Git host in your browser.

Let’s break down this git push command:

The output should look like this:

Any time you want to set up a new repository, you can repeat steps 12-14, with one exception: you only need to pass --set-upstream the first time you push. Afterwards you can just run the command:

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:

This might happen if you didn’t set init.defaultBranch to main in 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".

To push your branch, you have a few options:

Problem 2: SSH error

Here’s the error:

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 has commits in it

Here’s the error:

If you see an error like this, it means that when you created the repository on your Git host, it added a commit to try to help you out. That’s the "work that you do not have locally" in the error message.

You should be able to fix this by redoing Step 12. Then Step 14 should work.

We’re not going to cover collaboration at all in this tutorial, but here are a few more commands that might be useful when using Git on your own:

Part of the git(1) suite