First steps: Making commits

1   Set up a new code project

Git is version control software used for keeping track of the changes in coding projects. A folder containing files being tracked by git is called a repository. After you've created a repository (that is, after you've told git to watch a folder of code), git will be ready to record the incremental changes that happen to the code. However, we get to decide exactly which changes are recorded.

This tutorial will walk you through using git with a very simple Python project. (You don't need Python installed. We're not going to run this file. It's just to give git some actual code to work with.) Code examples that begin with $ are meant to be entered into the git bash command line.

To start, we're going to create a directory to put our fake project in:

$ cd ~                  # Go to our home directory
$ mkdir git_practice    # Make the new directory
$ cd git_practice       # Navigate to the new directory

We're also going to put a file in our new directory. Create a file called hello.py that looks like this:

print("Hello, world!")

2   Tell git to watch a directory

To tell git that you want to the current directory to be a repository (that is, you want git to watch this directory), you use the following command:

$ git init

That's it!

3   Ask git what our workspace looks like

Now that you've run git init, we can use git commands in our directory. Let's start with git status, which tells us what's going on in our working directory.

$ git status
On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        hello.py

nothing added to commit but untracked files present (use "git add" to track)

Git lists hello.py under "Untracked files". That's because git init only tells git that we want to use this directory. To track individual files, we need to tell git which files to watch or "track".

4   Tell git to track a file

You can use git add <filename> to have git start tracking a file

$ git add hello.py

To check what we've accomplished, use git status like before:

$ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

        new file:   hello.py

Now git is specifically watching our hello.py file.

5   Commit a new file to the repository

You probably noticed that the last git status listed our file under "Changes to be committed". That's because adding a new file (or a change to an existing file) to the permanent record of the repository is a two-step process.

The first step is staging. This is like putting items in a moving box but leaving the box open. We might put more things in or take things out--it's not permanent yet. We staged our new file with git add hello.py; we told git to add hello.py to a box but to leave the top open for now.

The second step is the commit. Making a commit takes all the changes we've staged (the things we've put in the box) and adds them to the permanent record of the repository (seals the box and puts it in storage).

To make a commit, you first have to have something staged. We already did this with git add hello.py, which is why hello.py is now listed under "Changes to be committed".

Now let's actually make the commit. The base command is git commit. However, it's good practice to also add a short note or message that describes the commit; it's like writing the contents of a box on the outside of the box. The easiest way to do this is with the message option (-m). So to make the commit with the message "New repo: added hello.py", run this command:

$ git commit -m "New repo: added hello.py"
[master (root-commit) 823459f] New repo: added hello.py
 1 file changed, 1 insertion(+)
 create mode 100644 hello.py

And that's it! This version of hello.py has been committed to the record that git keeps about our project. We can double check that our commit worked by running git status:

$ git status
On branch master
nothing to commit, working tree clean

6   Commit a change to a file

Now that git is tracking hello.py, it will alert us when the file changes.

First, change hello.py so it looks like this:

to_print = "Hello, world!"
print(to_print)

Now ask git if anything has changed:

$ git status
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   hello.py

no changes added to commit (use "git add" and/or "git commit -a")

Git sees that hello.py has changed. Remember that adding these changes to the repository record is a two step process:

1. Stage (add to the box)
2. Commit (seal the box)

So let's tell git to stage the changes made to hello.py, then check our git status.

$ git add hello.py
$ git status
On branch master
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   hello.py

Now let's make the commit and check that it worked.

$ git commit -m "Added a variable to hello.py"
[master 7d6a299] Added a variable to hello.py
 1 file changed, 2 insertions(+), 1 deletion(-)

$ git status
On branch master
nothing to commit, working tree clean

7   Look at the list of commits

The whole point of commits is to keep track of the incremental changes we make to our code. So we need a way to look back at the list of commits we've made. This is done with the git log command. However, the standard git log command puts out a lot of information we don't necessarily need. If you're using the .gitconfig file listed above, you can use git shortlog to see a customized version of git log that is a little simpler:

$ git shortlog
* 7d6a299 -  (HEAD -> master) Added a variable to hello.py
* 823459f -  New repo: added hello.py

Each * marks a commit. Next to that is the commit's ID number or "hash". For our most recent commit, this is 7d6a299. If you've been following along with this guide, your hashes will likely be different because git generates unique ID's for every commit. That's okay. We won't be directly referencing the hashes in this tutorial.

After the hash is the commit message we wrote. (HEAD -> master) marks what the most recent commit is. Don't worry about this just yet, we'll get to it.

Next in "A Brief Intro to Git": Branches and Merging