Reading History

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

git log -1

commit 60e13bdaf4dd2f895e9b562c4a8ee9ea289d2af7
Author: Deniz Kaya <[email protected]>
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

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:

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:

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

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:

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:

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

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:

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”:

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

git show --stat 43370ca

commit 43370ca23c4b30992ea9857c6282416de8e0a816
Author: Deniz Kaya <[email protected]>
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:

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.