1.1 Installation and setup

The most common way to use Git is via a command-line program called git, which lets us transform an ordinary Unix directory into a repository (or repo for short) that enables us to track changes to our project.³ In this section, we’ll begin by installing Git (if necessary) and doing some one-time configuration.

Before doing anything else, we first need to check to see if Git is installed on the current system. As a reminder, we’re working in the Unix tradition, so it is strongly recommended that you use macOS or Linux. Microsoft Windows users are encouraged to set up a Linux-compatible development environment by following the Windows steps in Learn Enough Dev Environment to Be Dangerous or use a Linux-based cloud IDE (which is also covered in Learn Enough Dev Environment to Be Dangerous).

The easiest way to check for Git is to start a terminal window and use which⁴ at the command line to see if the git executable is already present:

$ which git
/usr/local/bin/git

If the result is empty or if it says the command is not found, it means you have to install Git manually. To do this, follow the instructions at “Getting Started – Installing Git” in the official Git documentation. (This will likely give you an opportunity to apply some technical sophistication (Box 1.2).)

The next step is to ensure that you have a sufficiently recent version of Git, which you can check as follows:

$ git --version
git version 2.31.1    # should be at least 2.28.0

If the version isn’t recent enough, then you should either install Git via the instructions at “Getting Started – Installing Git” or follow one of the suggestions below:

• Cloud IDE: If using the cloud IDE recommended in Learn Enough Dev Environment to Be Dangerous, run the command in Listing 1.1.
• macOS: If using macOS, run the command in Listing 1.2. (If you don’t have Homebrew installed, first follow the instructions to install Homebrew.)

$ source <(curl -sL https://cdn.learnenough.com/upgrade_git)

$ brew upgrade git

After installing Git but before starting a project, we need to perform a few one-time setup steps, as shown in Listing 1.3. These are global setups, meaning you only have to do them once per computer. (Don’t worry about the meaning or structure of these commands at this stage.)

$ git config --global user.name "Your Name"
$ git config --global user.email your.email@example.com
$ git config --global init.defaultBranch main

The first two configuration settings allow Git to identify changes in your projects by name and email address, which is especially helpful when collaborating with others (Chapter 4). Note that the name and email you use in Listing 1.3 will be viewable in any projects you make public, so don’t expose any information you’d rather keep private.

The third line in Listing 1.3 sets the default Git branch name to main, which is the current recommended default. You should be aware that the default branch name for the first 15+ years of Git’s existence was master, so you will invariably encounter many Git repositories that use master instead of main.⁵ (Being able to deal with this sort of situation is a hallmark of technical sophistication (Box 1.2).) See the Learn Enough blog post “Default Git Branch Name with Learn Enough and the Rails Tutorial” for more information.

In addition to the configuration in Listing 1.3, Learn Enough Git to Be Dangerous includes some optional advanced setup (Section 4.6) that I recommend you complete at some point. If you already have some familiarity with Git, or if you’re an experienced user of the Unix command line, I recommend completing the steps in Section 4.6 at this time, but otherwise I recommend deferring the advanced setup until later.

1.2 Initializing the repo

Now it’s time to start creating a project and put it under version control with Git. To see how Git works and what benefits it brings, it helps to have a concrete application in mind, so we’ll be tracking changes in a simple project consisting of a small website consisting of two pages, a Home page and an About page.⁶ We’ll begin by making a directory with the generic name website inside a repositories directory called repos:

[~]$ mkdir -p repos/website

Here we’ve used the “make directory” command mkdir covered in Learn Enough Command Line to Be Dangerous, together with the -p option, which arranges for mkdir to create intermediate directories as required (in this case, repos). Note also that I’ve included the current directory in the prompt (in this case, [~]) as arranged by the configuration in Listing 4.15.

After making the directory, we can cd into it as follows:

[~]$ cd repos/website/
[website]$

(Recall that you can use tab completion when changing directories, so in real life I would probably type something like cd re⇥w⇥.)

Even though the website directory is empty, we can already convert it to a repository, which you can think of as a sort of enhanced Unix directory with the additional ability to track changes to every file and subdirectory. The way to create a new repository with Git is with the init command (short for “initialize”), which creates a special hidden directory called .git where Git stores the information it needs to track our project’s changes. (It’s the presence of a properly configured .git directory that distinguishes a Git repository from a regular directory.)

All Git commands consist of the command-line program git followed by the name of the command, so the full command to initialize a repository is git init, as shown in Listing 1.4.

[website]$ git init
Initialized empty Git repository in /Users/mhartl/repos/website/.git/
[website (main)]$

The prompt shown in Listing 1.4 reflects both the Bash customization from Learn Enough Text Editor to Be Dangerous and the advanced setup in Section 4.6.2, so your prompt may differ.⁷ In particular, the prompt in the highlighted line in Listing 1.4 shows the name of the current Git branch, called main. Don’t worry about what this means now; we’ll discuss branches starting in Section 3.3.

1.3 Our first commit

Git won’t let us complete the initialization of the repository while it’s empty, so we need to make a change to the current directory. We’ll make a more substantive change in a moment, but for now we’ll follow a common convention and simply use touch to create an empty file (as mentioned in Learn Enough Command Line to Be Dangerous). In this case, we’re making a simple website, and the near-universal convention is to call the main page index.html:

[website (main)]$ touch index.html

Having created this first file, we can use the git status command to see the result:

[website (main)]$ git status
On branch main

No commits yet

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

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

We see here that the index.html file is “untracked”, which means Git doesn’t yet know about it. We can add it using the git add command:

[website (main)]$ git add -A

Here the -A option tells Git to add all untracked files, even though in this case there’s only one. In my experience, 99% of the time you add files you’ll want to add them all, so this is a good habit to cultivate, and learning how to add individual files is left as an exercise (Section 1.3.1). (By the way, the nearly equivalent command git add ., where the dot refers to the current directory, is also common.)⁸

We can see the result of git add -A by running git status again:

[website (main)]$ git status
On branch main

No commits yet

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

As implied by the word “unstage”, the status of the file has been promoted from untracked to staged, which means the file is ready to be added to the repository. Untracked/unstaged and staged are two of the four states commonly used by Git, as shown in Figure 1.1. (Technically, untracked and unstaged are different states, but the distinction is rarely important because git add tracks and stages files at the same time.)

Figure 1.1: The main Git status sequence for changing a file.

As shown in Figure 1.1, after putting changes in the staging area we can make them part of the local repository by committing them using git commit. (We’ll cover the final step from Figure 1.1, git push, in Section 2.3.) Most uses of git commit use the command-line option -m to include a message indicating the purpose of the commit (Box 1.4). In this case, the purpose is to initialize the new repository, which we can indicate as follows:

[website (main)]$ git commit -m "Initialize repository"
[main (root-commit) 44c52d4] Initialize repository
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 index.html

(I’ve shown my output here for completeness, but your details will vary.)

At this point, we can use git log to see a record of our commit:

[website (main)]$ git log
commit 44c52d432d294ef52bae5535dc6dcb0993175a04 (HEAD -> main)
Author: Michael Hartl <michael@michaelhartl.com>
Date:   Thu Apr 1 10:30:38 2021 -0700

    Initialize repository

The commit is identified by a hash, which is a unique string of letters and numbers that Git uses to label the commit and which lets Git retrieve the commit’s changes. In my case, the hash appears as

44c52d432d294ef52bae5535dc6dcb0993175a04

but since each hash is unique your result will differ. The hash is often referred to as a “SHA” (pronounced shah) because of the acronym for the Secure Hash Algorithm used to generate it. We’ll put these SHAs to use in Section 3.4, and several more advanced Git operations require them as well.

1.4 Viewing the diff

It’s often useful to be able to view the changes represented by a potential commit before making it. To see how this works, let’s add a little bit of content to index.html by redirecting the output of echo to make a “hello, world” page:

[website (main)]$ echo "hello, world" > index.html

Recall from Learn Enough Command Line to Be Dangerous that the Unix diff utility lets us compare two files foo and bar by typing

$ diff foo bar

Git has a similar function, git diff, which by default just shows the difference between the last commit and unstaged changes in the current project:⁹

[website (main)]$ git diff
diff --git a/index.html b/index.html
index e69de29..4b5fa63 100644
--- a/index.html
+++ b/index.html
@@ -0,0 +1 @@
+hello, world

Because the content added in Section 1.3 was empty, here the diff appears simply as an addition:

+hello, world

We can commit this change by passing the -a option (for “all”) to git commit, which arranges to commit all the changes in currently existing files (Listing 1.5).

[website (main)]$ git commit -a -m "Add content to index.html"
[main 64f6529] Add content to index.html
 1 file changed, 1 insertion(+)

Note that the -a option includes changes only to files already added to the repository, so when there are new files it’s important to run git add -A as in Section 1.3 to make sure they’re added properly. It’s easy to get in the habit of running git commit -a and forget to add new files explicitly; learning how to deal with this situation is left as an exercise (Section 1.4.1).

Having added and committed the changes, there’s now no diff:

[website (main)]$ git diff
[website (main)]$

(In fact, simply adding the changes is sufficient; running git add -A would also lead to there being no diff. To see the difference between staged changes and the previous version of the repo, use git diff --staged.)

We can confirm that the change went through by running git log:

[website (main)]$ git log
commit 64f6529494cb0e193f05b0da75702feef854e176
Author: Michael Hartl <michael@michaelhartl.com>
Date:   Thu Apr 1 10:33:24 2021 -0700

    Add content to index.html

commit 44c52d432d294ef52bae5535dc6dcb0993175a04
Author: Michael Hartl <michael@michaelhartl.com>
Date:   Thu Apr 1 10:30:38 2021 -0700

    Initialize repository

1.5 Adding an HTML tag

We’ve now seen all of the major elements involved in the simplest Git workflow, so in this section and the next we’ll review what we’ve done and see how everything fits together. We’ll err on the side of making more frequent commits, representing relatively modest changes, but this isn’t necessarily how you should work in real life (Box 1.5). Still, it’s an excellent foundation, and it will give you a solid base on which to build your own workflow and development practices.

As in previous sections, we’ll be working on the main index.html file. Let’s start by opening this file in both a text editor and a web browser. My preferred method for doing this is at the command line using the atom and open commands (though the latter works only on macOS):

[website (main)]$ atom index.html
[website (main)]$ open index.html    # only on macOS; otherwise, use a GUI

If you’re not on a Mac (or even if you are), you can open the directory using a graphical file browser and double-clicking the file to open it in the default browser (Figure 1.2). However you open the file, the results should appear approximately as shown in Figure 1.3 and Figure 1.4.

Figure 1.2: Viewing index.html in a filesystem browser.

Figure 1.3: The initial HTML file opened in Atom.

Figure 1.4: The initial HTML file viewed in a web browser.

At this point, we’re ready to make a change, which is to promote “hello, world” from ordinary text to a top-level (Level 1) heading. In HTML, the language of the World Wide Web, the way to do this is with a tag—in this case, the Level 1 header tag h1. Most browsers set h1 tags in a large font, so the text hello, world should look bigger when we’re done. To make the change, replace the current contents of index.html with the contents shown in Listing 1.6. (In this and all other examples of editing text, you’ll learn more if you type in everything by hand instead of copying and pasting.)

<h1>hello, world</h1>

Listing 1.6 shows the basic structure used by most HTML tags. First, there’s an opening tag that looks like <h1>, where the angle brackets < and > surround the tag name (in this case, h1). After the content, there’s a closing tag that’s the same as the opening tag, except with an extra slash after the opening angle bracket: </h1>. (Note that, as with addresses on the World Wide Web, this is a slash, not a backslash (a common confusion humorously referenced in the xkcd comic strip “Trade expert”).)

Upon refreshing the web browser, the index page should appear something like Figure 1.5. As promised, the font size of the text for the top-level heading is bigger (and bolder, too).

Figure 1.5: The result of adding an h1 tag.

As before, we’ll run git status and git diff to learn more about what we’re going to commit to Git, though with experience you’ll come to run these commands only when necessary. The status simply indicates that index.html has been modified:

[website (main)]$ git status
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   index.html

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

Meanwhile, the diff shows that one line has been deleted (indicated with -) and another added (indicated with +):

[website (main)]$ git diff
diff --git a/index.html b/index.html
index 4b5fa63..45d754a 100644
--- a/index.html
+++ b/index.html
@@ -1 +1 @@
-hello, world
+<h1>hello, world</h1>

As with the Unix diff utility, modified sections of code or markup are shown as close to each other as possible so that it’s clear at a glance what changed.¹⁰

At this point, we’re ready to commit our changes. In Listing 1.5 we used both the -a and -m options to commit all pending changes while adding a commit message, but in fact the two can be combined as -am (Listing 1.7).

[website (main)]$ git commit -am "Add an h1 tag"

Using the -am combination as in Listing 1.7 is common in idiomatic Git usage.

1.6 Adding HTML structure

Although the web browser correctly rendered the h1 tag in Figure 1.5, properly formatted HTML pages have more structure than just bare h1 or p tags. In particular, each page should have an html tag consisting of a head and a body (identified with head and body tags, respectively), as well as a “doctype” identifying the document type, which in this case is a particular version of HTML called HTML5. (Don’t worry about these details now; we’ll cover them in more depth in Learn Enough HTML to Be Dangerous.)

Applying these general considerations to index.html leads to the full HTML structure shown in Listing 1.8. This includes the h1 tag from Listing 1.6 and the paragraph tag from Figure 1.6. (The title tag, included inside the head tag, is empty, but in general every page should have a title, and adding one for index.html is left as an exercise (Section 1.6.1).)

 1<!DOCTYPE html>
 2<html>
 3  <head>
 4    <title></title>
 5  </head>
 6  <body>
 7    <h1>hello, world</h1>
 8    <p>Call me Ishmael.</p>
 9  </body>
10</html>

Because this is a lot more content than our previous iteration (Listing 1.6), it’s a good idea to go through it line by line:

1. The document type declaration
2. Opening html tag
3. Opening head tag
4. Opening and closing title tags
5. Closing head tag
6. Opening body tag
7. Top-level heading
8. Paragraph from the exercises (Section 1.5.1)
9. Closing body tag
10. Closing html tag

As usual, we can see the changes represented by our addition using git diff (Listing 1.9).

[website (main)]$ git diff
diff --git a/index.html b/index.html
index 4b5fa63..afcd202 100644
--- a/index.html
+++ b/index.html
@@ -1 +1,10 @@
-<h1>hello, world</h1>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title></title>
+  </head>
+  <body>
+    <h1>hello, world</h1>
+    <p>Call me Ishmael.</p>
+  </body>
+</html>

Despite the extensive diffs in Listing 1.9, there are hardly any user-visible differences (Figure 1.7); the only change from Figure 1.6 is a small amount of space above the top-level heading. The structure is much better, though, and brings our page nearly into compliance with the HTML5 standard. (It’s not quite valid, because a nonblank page title is required by the standard; fixing this issue is left as an exercise (Section 1.6.1).)

Figure 1.7: Adding HTML structure makes hardly any difference in the appearance.

Since we haven’t added any files, using git commit -am suffices to commit all the changes (Listing 1.10).

[website (main)]$ git commit -am "Add some HTML structure"

1.7 Summary

Important commands from this section are summarized in Table 1.1.