Lesson 1 of 8 in Git and collaboration

How git stores history

Core9 minWritten for Git 2.28 or newer

Git is a program that records snapshots of a project folder. Each snapshot is called a commit, and every commit points back to the commit before it, so the whole history forms a chain you can walk, compare and return to.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Linux and the shell

The problem this solves

Without version control, history lives in file names like report-final-v3-really-final. Two people editing the same folder overwrite each other, and nobody can say what changed between Tuesday and today.

In DevOps the folder holds more than application code. It also holds pipeline files, server definitions and configuration. When something breaks in production, the first question is what changed, and git is where that answer is kept. Pipelines usually start from git too: a push is what triggers a build or a deploy.

Many learners memorise commands without a picture of what those commands act on. Almost every confusing git moment gets simpler once you know what a commit is, what a branch is, and what HEAD points at.

How it works

History is a chain of commits with labels on it
History is a chain of commits with labels on itCommit C points to its parent B, B points to A, the branch name main points to C, and HEAD points to main to show where you are.parentparentpoints topoints toCommit Afirst, has no parentCommit Bparent is ACommit Cparent is Bmainbranch: a movable labelHEADwhere you are now
  • Data
  • Control
  • People and clients

Commit C points to its parent B, B points to A, the branch name main points to C, and HEAD points to main to show where you are.

  1. Commit C to Commit B: parent
  2. Commit B to Commit A: parent
  3. main to Commit C: points to
  4. HEAD to main: points to
What one commit contains
What one commit containsA commit points to a tree, which is a folder listing; the tree names each file and points to its stored content; the commit also points to its parent commit.1 snapshot2 names a.txt3 names b.txt4 parentCommitmessage, author, timeTreethe folder listingContent of a.txtstored onceContent of b.txtreused if unchangedParent committhe one before
  • Data

A commit points to a tree, which is a folder listing; the tree names each file and points to its stored content; the commit also points to its parent commit.

  1. Commit to Tree: 1 snapshot
  2. Tree to Content of a.txt: 2 names a.txt
  3. Tree to Content of b.txt: 3 names b.txt
  4. Commit to Parent commit: 4 parent

A commit is a full snapshot of every tracked file at one moment, plus a message, an author, a time and a link to its parent. The second diagram shows the parts. Git stores each file's content once and reuses it whenever the file did not change, so snapshots stay small.

Because each commit names its parent, history is a chain. When two lines of work are merged, a commit gets two parents, so the proper name for the whole structure is a directed acyclic graph, or DAG: arrows run one way and never loop. A commit's ID is a hash worked out from its contents and its parent, which is why a commit never changes. Altering anything produces a different commit with a different ID.

A branch is only a name that points at one commit. In the first diagram main is a label on commit C. HEAD is a pointer to where you are now, usually to a branch. When you make a new commit, git creates it with the current commit as parent and moves the branch label forward. Nothing else moves.

Try it yourself

Everything below happens in a throwaway folder inside your home directory. Use a Linux or macOS shell, or WSL on Windows. You need git 2.28 or newer for git init -b.

  1. 1
    Create a repository
    mkdir git-lab-1 && cd git-lab-1
    git init -b main
    git config user.name "Your Name"
    git config user.email "you@example.com"

    git init creates a hidden .git folder. That folder is the repository: all history lives inside it. The two config lines apply to this repository only.

  2. 2
    Make the first commit
    echo "one" > a.txt
    git add a.txt
    git commit -m "Add a.txt"
  3. 3
    Ask git what that commit is
    git cat-file -t HEAD
    git cat-file -p HEAD

    You should see

    commit

    The first line prints the object type. The second prints the commit itself: a tree line, author and committer lines and your message. A first commit has no parent line.

  4. 4
    Add a second commit and see the parent link
    echo "two" >> a.txt
    git commit -am "Extend a.txt"
    git cat-file -p HEAD
    git log --oneline --graph

    This time git cat-file -p HEAD shows a parent line holding the ID of the first commit. -a stages edits to files git already tracks.

  5. 5
    Look at the labels
    cat .git/HEAD
    cat .git/refs/heads/main

    You should see

    ref: refs/heads/main
    <the ID of your latest commit>

    HEAD is a small text file that names a branch. The branch is another small file that holds a commit ID. That is the whole mechanism.

What breaks, and where to look

  • fatal: not a git repository (or any of the parent directories): .git

    WHY IT HAPPENS
    You are in a folder that is not inside a repository, or you never ran git init or git clone.
    CHECK FIRST
    Run pwd to see where you are and ls -a to look for a .git folder. git rev-parse --show-toplevel prints the repository root when you are inside one.
  • fatal: your current branch 'main' does not have any commits yet

    WHY IT HAPPENS
    The repository exists but nothing has been committed. Commands that read history have nothing to show.
    CHECK FIRST
    Run git status. If files are listed as untracked, run git add <file> and git commit -m "message".
  • git status lists thousands of files you never created, or a different project shows up.

    WHY IT HAPPENS
    A .git folder exists higher up, for example from running git init in your home folder by accident. Git uses the nearest .git above you.
    CHECK FIRST
    Run git rev-parse --show-toplevel. If it prints a folder you did not expect, look at what lives there before changing anything. Deleting a .git folder deletes that repository's whole history.

When not to use this

  • Git keeps every version of every file forever. Large binaries such as videos, disk images and build output make a repository slow and big. Put those in an artifact registry or object storage instead.
  • A repository on one laptop is not a backup. If the disk dies, the history dies with it. A remote copy is what protects you, and the remotes concept covers that.

Check yourself

What does a commit contain?

A snapshot of the tracked files, a message, an author and time, and a link to its parent commit.

What is a branch?

A name that points at one commit. Committing moves the name forward to the new commit.

What does HEAD tell you?

Where you are now. Usually it points at a branch, and the branch points at the latest commit.

Lesson 31 of 92 in the DevOps path

Search

Search cheat sheets and projects