Read the Story of a Repository

You have opened a repository you did not create. It belongs to Fern & Fig, a small plant shop, and it already has eleven commits. Before changing anything, you want to know what happened here.

That is what a history is for. You do not need to understand every line of its output at once. You need one reliable place to begin.

What one commit holds

You already know a commit as a snapshot with a reason attached. Here is the slightly fuller version you need for reading an existing history.

A commit records:

• a snapshot of every tracked file in the project;

• a message, author, and date;

• a link into the earlier history. An ordinary commit has one parent, while the first commit has none. Chapter 6 will refine that rule for merges.

That last link is what turns separate snapshots into a story. Git can follow the links backward from the newest commit to the beginning.

A commit does not store a ready-made list of changed lines. When Git shows a change, it calculates the difference between that commit’s snapshot and another snapshot. Keeping those two ideas separate will make the next lessons much easier to read.

Ask for the history

git log reads the commits reachable from where you are and prints them newest first. With no options, it shows the ordinary human-readable form: the commit identifier, author, date, and message.

On a normal computer, a long Git result often opens in a pager, a full-screen view you can scroll. Press q to leave it. The terminal in this course deliberately disables the pager, so the same output simply scrolls past.

Run the plain command now:

git log

Start at the top. The newest message is Document where stock lives. Below it is a longer message about fixing a missing decimal point. Farther down are short messages such as spacing and wip that give you almost no help.

That mix is normal. A history is written by people over time, and not every message will be good. You are not expected to decode all eleven commits in one look. First ask a small question: what is newest, who made it, and what does the message claim happened?

The long identifier

Each entry begins with commit and a long string such as ed9fce3016100405187bbe307b1731f2bb91ba5b. That is the commit’s identifier. It names exactly one commit in this repository.

You rarely need to type the whole thing. A short beginning such as ed9fce3 is enough when it is unique in the repository. Git will tell you if the part you supplied could name more than one commit.

The identifier is a label, not a score and not something to memorize. Copy it when you need to ask about that commit, then let Git do the remembering.

You have done the useful first pass: newest at the top, messages as signposts, identifiers as labels. Next you will open one commit and see how its snapshot differs from the one before it.