You’re reading Ry’s Git Tutorial
Now that you have a basic understanding of version control systems in general, we can start experimenting with Git. Using Git as a VCS is a lot like working with a normal software project. You’re still writing code in files and storing those files in folders, only now you have access to a plethora of Git commands to manipulate those files.
For example, if you want to revert to a previous version of your project, all you have to do is run a simple Git command. This command will dive into Git’s internal database, figure out what your project looked like at the desired state, and update all the existing files in your project folder (also known as the working directory). From an external standpoint, it will look like your project magically went back in time.
This module explores the fundamental Git workflow: creating a repository, staging and committing snapshots, configuring options, and viewing the state of a repository. It also introduces the HTML website that serves as the running example for this entire tutorial. A very basic knowledge of HTML and CSS will give you a deeper understanding of the purpose underlying various Git commands but is not strictly required.
Create the Example Site
Before we can execute any Git commands, we need to create the example
project. Create a new folder called
my-git-repo to store the
project, then add a file called
index.html to it. Open
index.html in your favorite text editor and add the following
<title>A Colorful Website
>A Colorful Website
<p>This is a website about color!
<li>Nothing going on (yet)
Save the file when you’re done. This serves as the foundation of our
example project. Feel free to open the
index.html in a web browser
to see what kind of website it translates to. It’s not exactly pretty,
but it serves our purposes.
Initialize the Git Repository
Now, we’re ready to create our first Git repository. Open a command prompt (or Git Bash for Windows users) and navigate to the project directory by executing:
/path/to/my-git-repo is a path to the folder created in
the previous step. For example, if you created
my-git-repo on your
desktop, you would execute:
Next, run the following command to turn the directory into a Git repository.
This initializes the repository, which enables the rest of Git’s
powerful features. Notice that there is now a
.git directory in
my-git-repo that stores all the tracking data for our repository
(you may need to enable hidden files to view this folder). The
.git folder is the only difference between a Git repository and an
ordinary folder, so deleting it will turn your project back into an unversioned
collection of files.
View the Repository Status
Before we try to start creating revisions, it would be helpful to view the status of our new repository. Execute the following in your command prompt.
This should output something like:
# Initial commit
# (use "git add <file>..." to include in what will be committed)
index.htmlnothing added to commit but untracked files present (use "git add" to track)
On branch master portion for the time being, this
status message tells us that we’re on our initial commit and that we have
nothing to commit but “untracked files.”
An untracked file is one that is not under version control.
Git doesn’t automatically track files because there are often project
files that we don’t want to keep under revision control. These include
binaries created by a C program, compiled Python modules (
files), and any other content that would unnecessarily bloat the repository. To
keep a project small and efficient, you should only track source files
and omit anything that can be generated from those files. This latter
content is part of the build process—not revision control.
Stage a Snapshot
So, we need to explicitly tell Git to add
index.html to the
repository. The aptly named
git add command tells Git to start
In place of the “Untracked files” list, you should see the following status.
Changes to be committed:
# (use "git rm --cached <file>..." to unstage)
new file: index.html
We’ve just added
index.html to the
snapshot for the next commit. A snapshot represents the state
of your project at a given point in time. In this case, we created a snapshot
with one file:
index.html. If we ever told Git to revert to this
snapshot, it would replace the entire project folder with this one file,
containing the exact same HTML as it does right now.
Git’s term for creating a snapshot is called staging because we can add or remove multiple files before actually committing it to the project history. Staging gives us the opportunity to group related changes into distinct snapshots—a practice that makes it possible to track the meaningful progression of a software project (instead of just arbitrary lines of code).
Commit the Snapshot
We have staged a snapshot, but we still need to commit it to the project history. The next command will open a text editor and prompt you to enter a message for the commit.
Create index page for the message, leave the remaining
text, save the file, and exit the editor. You should see the message
files changed among a mess of rather ambiguous output. This changed file
As we just demonstrated, saving a version of your project is a two step process:
- Staging. Telling Git what files to include in the next commit.
- Committing. Recording the staged snapshot with a descriptive message.
Staging files with the
git add command doesn’t actually
affect the repository in any significant way—it just lets us get our
files in order for the next commit. Only after executing
commit will our snapshot be recorded in the repository. Committed
snapshots can be seen as “safe” versions of the project. Git will
never change them, which means you can do almost anything you want to your
project without losing those “safe” revisions. This is the
principal goal of any version control system.
View the Repository History
git status now tells us that there is
to commit, which means our current state matches what is stored in the
git status command will only show us
uncommitted changes—to view our project history, we need a new
When you execute this command, Git will output information about our one and only commit, which should look something like this:
unknown <[email protected](none)>
Wed Jan 11 00:45:10 2012 -0600Create index page
Let’s break this down. First, the commit is identified with a very
large, very random-looking string (
b650e4b...). This is an SHA-1
checksum of the commit’s contents, which ensures that the commit will
never be corrupted without Git knowing about it. All of your SHA-1 checksums
will be different than those displayed in this tutorial due to the different
dates and authors in your commits. In the next module, we’ll see how a
checksum also serves as a unique ID for a commit.
Next, Git displays the author of the commit. But since we haven’t told
Git our name yet, it just displays
unknown with a generated
username. Git also outputs the date, time, and timezone (
when the commit took place. Finally, we see the commit message that was entered
in the previous step.
Before committing any more snapshots, we should probably tell Git who we
are. We can do this with the
git config command:
Be sure to replace
Your Name and
[email protected] with your actual name and email. The
--global flag tells Git to use this configuration as a default for
all of your repositories. Omitting it lets you specify different user
information for individual repositories, which will come in handy later on.
Create New HTML Files
Let’s continue developing our website a bit. Start by creating a file
orange.html with the following content.
<title>The Orange Page
>The Orange Page
<p>Orange is so great it has a
</span>named after it.
Then, add a
<title>The Blue Page
>The Blue Page
<p>Blue is the color of the sky.
Stage the New Files
Next, we can stage the files the same way we created the first snapshot.
Notice that we can pass more than one file to
git add. After
adding the files, your status output should look like the following:
Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
new file: blue.html
new file: orange.html
git log. It only outputs the first commit, which
tells us that
orange.html have not yet
been added to the repository’s history. Remember, we can see
staged changes with
git status, but not with
log. The latter is used only for committed changes.
Commit the New Files
Let’s commit our staged snapshot:
Create blue and orange pages as the commit message, then
save and close the file. Now,
git log should output two commits,
the second of which reflects our name/email configuration. This project history
can be visualized as:
Each circle represents a commit, the red circle designates the commit we’re currently viewing, and the arrow points to the preceding commit. This last part may seem counterintuitive, but it reflects the underlying relationship between commits (that is, a new commit refers to its parent commit). You’ll see this type of diagram many, many times throughout this tutorial.
Modify the HTML Pages
git add command we’ve been using to stage
new files can also be used to stage modified files. Add the
following to the bottom of
index.html, right before the closing
>The Orange Page
>The Blue Page
Next, add a home page link to the bottom of
blue.html (again, before the
>Return to home page
You can now navigate between pages when viewing them in a web browser.
Stage and Commit the Snapshot
Once again, we’ll stage the modifications, then commit the snapshot.
"Add navigation links"
-m option lets you specify a commit message on the command
line instead of opening a text editor. This is just a convenient shortcut (it
has the exact same effect as our previous commits).
Our history can now be represented as the following. Note that the red circle, which represents the current commit, automatically moves forward every time we commit a new snapshot.
Explore the Repository’s History
git log command comes with a lot of formatting options, a
few of which will be introduced throughout this tutorial. For now, we’ll
just use the convenient
Condensing output to a single line is a great way to get a high-level
overview of a repository. Another useful configuration is to pass a filename to
This displays only the
blue.html history. Notice that the
Create index page commit is missing, since
blue.html didn’t exist in that snapshot.
In this module, we introduced the fundamental Git workflow: edit files, stage a snapshot, and commit the snapshot. We also had some hands-on experience with the components involved in this process:
The distinction between the working directory, the staged snapshot, and committed snapshots is at the very core of Git version control. Nearly all other Git commands manipulate one of these components in some way, so understanding the interplay between them is a fantastic foundation for mastering Git.
The next module puts our existing project history to work by reverting to previous snapshots. This is all you need to start using Git as a simple versioning tool for your own projects.
- Create a Git repository in the current folder.
- View the status of each file in a repository.
git add <file>
- Stage a file for the next commit.
- Commit the staged files with a descriptive message.
- View a repository’s commit history.
git config --global user.name "<name>"
- Define the author name to be used in all repositories.
git config --global user.email <email>
- Define the author email to be used in all repositories.
Sign up for my low-volume mailing list to find out when new content is released. Next up is a comprehensive Swift tutorial planned for late January.
You’ll only receive emails when new tutorials are released, and your contact information will never be shared with third parties. Click here to unsubscribe.