To model a typical situation, let’s create a repository for your personal website from the directory ~/public_html and place it in a Git repository.

If you don’t have content for your personal website in ~/public_html, create the directory and place some simple content in a file called index.html:

$ mkdir ~/public_html
$ cd ~/public_html
$ echo 'My website is alive!' > index.html

To turn ~/public_html or any directory into a Git repository, run git init:

$ git init

Initialized empty Git repository in .git/

Git doesn’t care whether you start with a completely empty directory or with a directory full of files. In either case, the process of converting the directory into a Git repository is the same.

To signify that your directory is a Git repository, the git init command creates a hidden directory, called .git, at the top level of your project. Whereas CVS and Subversion place revision information in CVS and .svn subdirectories within each of your project’s directories, Git places all its revision information in this one top-level .git directory. The contents and purpose of the data files are discussed in more detail in Inside the .git directory.

Everything in your ~/public_html directory remains untouched. Git considers it your project’s working directory, or the directory where you alter your files. In contrast, the repository hidden within .git is maintained by Git.

git init creates a new Git repository. Initially, each Git repository is empty. To manage content, you must explicitly deposit it in the repository. Such a conscious step separates scratch files from important files.

Use git add file to add file to the repository:

$ git add index.html

After an add, Git knows that the file, index.html, is to remain in the repository. However, so far Git has merely staged the file, an interim step before committal. Git separates the add and commit steps to avoid volatility. Imagine how disruptive, confusing, and time-consuming it would be to update the repository each time you add, remove, or change a file. Instead, multiple provisional and related steps, such as an add, can be “batched,” keeping the repository in a stable, consistent state.

Running git status reveals this in-between state of index.html:

$ git status

# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached <file>..." to unstage)
#
#       new file: index.html

The command reports that the new file index.html will be added to the repository during the next commit.

In addition to actual changes to the directory and to file contents, Git records several other pieces of metadata with each commit, including a log message and the author of the change. A fully qualified git commit command supplies a log message and an author:

$ git commit -m "Initial contents of public_html" 
             --author="Jon Loeliger <[email protected]>"

Created initial commit 9da581d: Initial contents of public_html
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 index.html

You can provide a log message on the command line, but it’s more typical to create the message during an interactive editor session. This gives you an opportunity to compose a complete and detailed log message in your favorite editor. To open your favorite editor during a git commit, set your GIT_EDITOR environment variable:

# In tcsh
$ setenv GIT_EDITOR emacs

# In bash
$ export GIT_EDITOR=vim

After you commit the addition of the new file into the repository, git status indicates that there are no outstanding, staged changes to be committed:

$ git status

# On branch master
nothing to commit (working directory clean)

Git also takes the time to tell you that your working directory is clean, meaning the working directory has no unknown or modified files that differ from what is in the repository.

You don't exist. Go away!
Your parents must have hated you!
Your sysadmin must hate you!

Before making many commits to a repository, you should establish some basic environment and configuration options. At a bare minimum, Git must know your name and email address. You may specify your identity on every commit command line, as shown earlier, but that is the hard way and quickly becomes tedious.

Instead, save your identity in a configuration file using the git config command:

$ git config user.name "Jon Loeliger"
$ git config user.email "[email protected]"

You can also tell Git your name and email address using the GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL environment variables. If set, these variables override all configuration settings.

To show a few more features of Git, let’s make some modifications and create a complex history of changes within the repository.

Let’s commit an alteration to the index.html file. Open the file, convert it to HTML, and save the file:

$ cd ~/public_html

# edit the index.html file

$ cat index.html
<html>
<body>
My website is alive!
</body>
<html>

$ git commit index.html

When your editor comes up, enter a commit log entry, such as “Convert to HTML,” and exit the editor. There are now two versions of index.html in the repository.

Once you have one or more commits in the repository, you can inspect them in a variety of ways. Some Git commands show the sequence of individual commits; others show the summary of an individual commit; and still others show the full details of any commit in the repository.

The command git log yields a sequential history of the individual commits within the repository:

$ git log

commit ec232cddfb94e0dfd5b5855af8ded7f5eb5c90d6
Author: Jon Loeliger <[email protected]>
Date:   Wed Apr 2 16:47:42 2008 -0500

    Convert to HTML

commit 9da581d910c9c4ac93557ca4859e767f5caf5169
Author: Jon Loeliger <[email protected]>
Date:   Thu Mar 13 22:38:13 2008 -0500

    Initial contents of public_html

The entries are listed, in order, from most recent to oldest^[6] (the original file); each entry shows the commit author’s name and email address, the date of the commit, the log message for the change, and the internal identification number of the commit. The commit ID number is explained in Content-Addressable Names, and commits are discussed in Chapter 6.

To see more detail about a particular commit, use git show with a commit number:

$ git show 9da581d910c9c4ac93557ca4859e767f5caf5169

commit 9da581d910c9c4ac93557ca4859e767f5caf5169
Author: Jon Loeliger <[email protected]>
Date:   Thu Mar 13 22:38:13 2008 -0500

    Initial contents of public_html

diff --git a/index.html b/index.html
new file mode 100644
index 0000000..34217e9
--- /dev/null
+++ b/index.html
@@ -0,0 +1 @@
+My website is alive!

If you run git show without an explicit commit number, it simply shows the details of the most recent commit.

Another view, show-branch, provides concise, one-line summaries for the current development branch:

$ git show-branch --more=10

[master] Convert to HTML
[master^] Initial contents of public_html

The phrase --more=10 reveals the most recent 10 versions, but only two exist so far and so both are shown. (The default lists only the most recent commit.) The name master is the default branch name.

Chapter 7 covers branches in more depth, and Viewing Branches describes the git show-branch command in more detail.

To see the differences between the two revisions of index.html, recall both full commit ID names and run git diff:

$ git diff 9da581d910c9c4ac93557ca4859e767f5caf5169 
      ec232cddfb94e0dfd5b5855af8ded7f5eb5c90d6 

diff --git a/index.html b/index.html
index 34217e9..40b00ff 100644
--- a/index.html
+++ b/index.html
@@ -1 +1,5 @@
+<html>
+<body>
 My website is alive!
+</body>
+<html>

This output should look familiar: it resembles what the diff program produces. As is the convention, the first revision, named 9da581d910c9c4ac93557ca4859e767f5caf5169, is the earlier version of the content, while the second revision, named ec232cddfb94e0dfd5b5855af8ded7f5eb5c90d6, is the newer one. Thus, a plus sign (+) precedes each line of new content.

Scared yet? Don’t worry about those intimidating hex numbers. Thankfully, Git provides many shorter, easier ways to do commands like this without having to produce large, complicated numbers.

Removing a file from a repository is analogous to adding a file but uses git rm. Suppose you have the file poem.html in your website content and it’s no longer needed:

$ cd ~/public_html
$ ls
index.html  poem.html

$ git rm poem.html
rm 'poem.html'

$ git commit -m "Remove a poem"
Created commit 364a708: Remove a poem
 0 files changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 poem.html

As with an addition, a deletion requires two steps: git rm expresses your intent to remove the file and stages the change, and then git commit realizes the change in the repository. Again, you can omit the -m option and type a log message, such as “Remove a poem.” interactively in your favorite text editor.

You can rename a file indirectly by using either a combination of git rm and git add, or you can rename it more quickly and directly with git mv. Here’s an example of the former:

$ mv foo.html bar.html
$ git rm foo.html
rm 'foo.html'
$ git add bar.html

In this sequence, you must execute mv foo.html bar.html at the onset lest git rm permanently delete the foo.html file from the filesystem.

Here’s the same operation performed with git mv.

$ git mv foo.html bar.html

In either case, the staged changes must be committed subsequently:

$ git commit -m "Moved foo to bar"
Created commit 8805821: Moved foo to bar
 1 files changed, 0 insertions(+), 0 deletions(-)
 rename foo.html => bar.html (100%)

Git handles file move operations differently than most akin systems, employing a mechanism based on the similarity of the content between two file versions. The specifics are described in Chapter 5.

If you followed the previous steps and made an initial repository in your ~/public_html directory, you can now create a complete copy, or clone, of that repository using the git clone command. This is how people around the world use Git to pursue pet projects on the same files and keep in sync with other repositories.

For the purposes of this tutorial, let’s just make a copy in your home directory and call it my_website:

$ cd ~
$ git clone public_html my_website

Although these two Git repositories now contain exactly the same objects, files, and directories, there are some subtle differences. You may want to explore those differences with commands such as:

$ ls -lsa public_html my_website
$ diff -r public_html my_website

On a local filesystem like this, using git clone to make a copy of a repository is quite similar to cp -a or rsync. However, Git supports a richer set of repository sources, including network names, for naming the repository to be cloned. These forms and usage are explained in Chapter 11.

Once you clone a repository, you are able to modify the cloned version, make new commits, inspect its logs and history, and so on. It is a complete repository with full history.