---
title: 'Reading History'
source: 'https://academia.sh/en/courses/introduction-to-version-control/reading-history'
course: 'Introduction to Version Control'
language: en
updated: '2026-08-17T18:10:47+00:00'
license: 'CC BY-SA 4.0'
---

# Reading History

Formatting the log's output; filtering by path, content, author, and time; revision-range notation, and reading the commit graph directly.

History has reached five commits. `git log --oneline` is enough to list these five
lines; but as history grows, the question changes. Instead of "what were the last
five commits," the questions become "who touched this file," "when was this line
added," "what happened between two versions." This lesson takes up the filtering and
formatting tools that answer those questions.

## The Default Format

```bash
git log -1
```

```
commit 60e13bdaf4dd2f895e9b562c4a8ee9ea289d2af7
Author: Deniz Kaya <deniz@ornek.test>
Date:   Tue Mar 5 14:20:00 2024 +0300

    Aramayı büyük/küçük harften bağımsız yap

    Terimler listede küçük harfle tutuluyor. Kullanıcı "Yığıt" yazdığında
    arama boş dönüyor, terim listede olduğu hâlde bulunamıyordu.

    grep çağrısına -i seçeneği eklendi; bu seçenek POSIX'te tanımlıdır ve
    ek bağımlılık getirmez.
```

The default format gives the ID at full length, the author and date on separate
lines, and the whole message indented. The `-1` option limits the output to a
single commit; any number can be given with `-n`.

The ID, date, and author fields shown in the output are specific to this
repository. When you run the same commands in your own repository, the IDs and
dates will differ; what stays fixed is the output's structure.

## Summary Formats

```bash
git log --oneline
```

```
60e13bd Aramayı büyük/küçük harften bağımsız yap
43370ca Üç veri yapısı terimi ekle
3132c78 Biçim örneğindeki yazımı düzelt
546c174 Terim arama betiği ekle
13d31bf Terim listesini ve biçim belgesini ekle
```

The shortened ID is kept just long enough to preserve uniqueness; its length can
grow as the repository grows. The short ID can be used in commands in place of the
full ID.

The `--graph` option draws history's graph structure along the left edge:

```bash
git log --oneline --graph
```

```
* 60e13bd Aramayı büyük/küçük harften bağımsız yap
* 43370ca Üç veri yapısı terimi ekle
* 3132c78 Biçim örneğindeki yazımı düzelt
* 546c174 Terim arama betiği ekle
* 13d31bf Terim listesini ve biçim belgesini ekle
```

Since there is no branching in this history, the drawing is a single column. If
there is branching, the columns multiply and merge points become visible; this
output will be read in the Branching and Collaboration course.

## Format Strings

The output's fields can be selected one by one:

```bash
git log --pretty=format:'%h %ad %s' --date=short
```

```
60e13bd 2024-03-05 Aramayı büyük/küçük harften bağımsız yap
43370ca 2024-03-05 Üç veri yapısı terimi ekle
3132c78 2024-03-04 Biçim örneğindeki yazımı düzelt
546c174 2024-03-04 Terim arama betiği ekle
13d31bf 2024-03-04 Terim listesini ve biçim belgesini ekle
```

Commonly used fields:

| String | Meaning |
|---|---|
| `%H` / `%h` | Commit ID / its shortened form |
| `%T` | The tree object's ID |
| `%P` | Parent commits' IDs |
| `%an` / `%ae` | Author's name / email |
| `%ad` / `%cd` | Author date / committer date |
| `%s` / `%b` | Subject line / body |

The `--date` option sets the date format: `short` gives only the day, `iso` gives
the full timestamp and time zone.

## Change Statistics

```bash
git log --oneline --stat
```

```
60e13bd Aramayı büyük/küçük harften bağımsız yap
 ara.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
43370ca Üç veri yapısı terimi ekle
 terimler.txt | 3 +++
 1 file changed, 3 insertions(+)
3132c78 Biçim örneğindeki yazımı düzelt
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
546c174 Terim arama betiği ekle
 ara.sh | 9 +++++++++
 1 file changed, 9 insertions(+)
13d31bf Terim listesini ve biçim belgesini ekle
 README.md    | 9 +++++++++
 terimler.txt | 3 +++
 2 files changed, 12 insertions(+)
```

Under every commit, the files it touched and the number of lines added and removed
are listed. If a commit's `--stat` output is long, that commit has most likely
combined more than one piece of work: the statistic is the audit tool for the
atomic-commit habit.

## Path Filtering

Commits that touch a specific file:

```bash
git log --oneline -- ara.sh
```

```
60e13bd Aramayı büyük/küçük harften bağımsız yap
546c174 Terim arama betiği ekle
```

The double-dash separator declares that everything after it is a path. Without the
separator, `ara.sh` gets interpreted as an attempt at a ref name; when a branch and
a file share the same name, the command becomes ambiguous. Always writing the
separator removes this ambiguity.

## Content Filtering

To find when a piece of text entered or left history:

```bash
git log --oneline -S 'grep -i'
```

```
60e13bd Aramayı büyük/küçük harften bağımsız yap
```

The `-S` option finds commits that **change the number of occurrences** of the
given string. That is, it returns not the commits that contain the string, but the
commits that add or remove it. It is the most direct tool when searching for a
behavior's origin: what is being searched for is not the line itself, but the
moment the line was born.

## Author and Time Filtering

```bash
git log --oneline --since="2024-03-05 00:00"
```

```
60e13bd Aramayı büyük/küçük harften bağımsız yap
43370ca Üç veri yapısı terimi ekle
```

`--since` selects everything after the given moment, `--until` everything before
it. When a time of day is added to the date, the boundary becomes exact; short
forms that give only the day can be interpreted differently.

There is a separate command for the distribution of contributions:

```bash
git shortlog -sn HEAD
```

```
     5	Deniz Kaya
```

`-s` asks for just the count, `-n` for descending order by count. When no ref is
given, the command reads its input from standard input; this is why `HEAD` has to
be written explicitly in scripts.

## Revision Range Notation

Two dots define a set of commits. `A..B` means "commits reachable from B but not
reachable from A":

```bash
git log --oneline HEAD~2..HEAD
```

```
60e13bd Aramayı büyük/küçük harften bağımsız yap
43370ca Üç veri yapısı terimi ekle
```

The notation `HEAD~2` means "two parents back." The definition is given over the
graph: reachability is the set of nodes reachable by following parent edges. This
is why range notation is also meaningful in branched histories; asking for
everything after the point where two branches diverged is done with the same
notation.

## Viewing a Single Commit

```bash
git show --stat 43370ca
```

```
commit 43370ca23c4b30992ea9857c6282416de8e0a816
Author: Deniz Kaya <deniz@ornek.test>
Date:   Tue Mar 5 09:05:00 2024 +0300

    Üç veri yapısı terimi ekle

    Ağaç, karma tablosu ve bağlı liste terimleri listede yoktu; bu terimler
    sorulduğunda arama betiği boş çıktı veriyordu.

    Karşılıklar Veri Yapıları kursunun sözlüğüyle aynı biçimde yazıldı.

 terimler.txt | 3 +++
 1 file changed, 3 insertions(+)
```

`git show` displays an object in a form suited to its type: metadata and diff for
a commit, an entry list for a tree, raw content for a blob.

## Reading the Graph Directly

Format strings are also useful for giving history's graph structure in its bare
form:

```bash
git log --format='%h %T %P'
```

```
60e13bd d23f16ee3533d05e3afd189a11551b6ec89f0898 43370ca23c4b30992ea9857c6282416de8e0a816
43370ca 8074917cfe2b0200648feaeeaf612170157dcc95 3132c7841e3e63c5eb968e37b301aa64dd1e8fb0
3132c78 01426328c4d751777bad684a17c7bc7941589603 546c174a007fdea08f907bd4d428cc87ce7e6148
546c174 21f7408f587a9837da6ae2ba960c74b756c79858 13d31bf17fdc8a5292b7fff288de94088d5c1440
13d31bf 378e434005c6c42021d4398a15e89149b0fd8671
```

Every line gives a node; the third column gives that node's edge. In the last
line, the third column is empty: the root commit has no parent. The values in the
first column reappear in the third column starting from the second line; the list
is the graph's edge-list representation. One of the three graph representations
defined in the Data Structures course shows up here directly.

## Summary

- The default log format gives the ID, author, date, and the whole message;
  `--oneline` reduces these to a single line.
- `--pretty=format:` selects fields one by one; `%H`, `%T`, `%P` give the commit,
  tree, and parent IDs.
- `--stat` shows the files touched and the line counts per commit.
- Path filtering is done with the double-dash separator, content filtering with
  `-S`; `-S` finds commits that change a string's occurrence count.
- The `A..B` notation defines commits reachable from B but not reachable from A.

## Next Step

The log says which commit touched which file, but it does not show the change's
content. What is more, changes not yet committed never appear in the log at all.
The next lesson takes up examining the differences between the three
regions — working directory and staging area, staging area and last commit,
between two commits — one at a time, and reading the diff output's format.