P2-14.1 Git as a Tool for Managing Change History¶

Section ID: P2-14.1 Version: v2026.07.20

In Part 2 Chapter 13, we created plots with Matplotlib and linked the output images into documents. A problem appears immediately at that point. If documents, code, images, and research notes all change together, it becomes hard later to remember "what changed, and why."

Git is a tool for recording that kind of change. It is not just a tool for saving code. It is better read as a device for tracking how documents and example code change across a learning process. You need this sense early so that, in Part 3, even in scenes where experiment conditions change often, such as baseline comparisons, preprocessing edits, and metric interpretation, you can still explain again what was changed, and why.

This section explains the basic distinctions among Git, version control, commit, staging area, and repository. If Chapters 11 through 13 were the stage of reading and checking data through arrays, tables, and plots, then the question here changes into how to leave those calculations and checks behind as bundles of changes. Git should not be read as a tool that suddenly appeared out of nowhere. It should be read as the record tool that lets you explain again the baseline comparisons, preprocessing edits, and metric interpretations in Part 3. When the later section continues into branches and deployment, also keep the Concept Glossary as a reference point.

Core Criteria: Git as a Tool for Managing Change History¶

• You can explain version control as "a record that lets you find a specific past state again after time has passed."
• You can understand a Git commit not as file saving but as a meaningful bundle of changes.
• You can explain intuitively the difference among the working tree, staging area, and repository.
• You can distinguish the roles of git status, git add, git commit, and git log.
• You can explain why learning documents and example code should be managed with Git.

Three Criteria¶

Saving a File and Leaving Change History Are Different¶

If you save a file, the current state remains. But it does not automatically explain why the previous state changed, or which files changed together.

For example, suppose you did the following work.

• Wrote the draft of one section.
• Added a script that generates plots.
• Created two output images.
• Edited the site table-of-contents settings.

These four things may look like separate tasks, but in practice they can form one meaningful bundle of change: "reflect the plot explanation of one section together with its linked assets."

Git records this kind of bundle as a commit.

Version Control Is Closer to Explaining Than to Going Back¶

When people first learn Git, they often understand it as "a tool that lets me go back if I make a mistake." That explanation is also correct. But here we take a slightly wider view.

Version control is a device for answering the following questions after time has passed.

• Which files changed?
• Why did they change?
• Which files changed together?
• When did a certain explanation enter the project?
• If a problem appeared, after which change did it appear?

The official Git book explains version control as a system that records file changes over time and lets you bring back specific versions later. Here, we apply that view to document writing and learning records.

The Basic Flow of Git¶

Here, we divide the Git flow into the following three spaces.

flowchart TD
  A["working directory<br/>where you edit current files"]
  B["staging area<br/>where you choose changes for this record"]
  C["repository<br/>history accumulated by commit"]

  A -->|"git add"| B
  B -->|"git commit"| C
  C -->|"check with git log"| C

The important point in this flow is that saving and committing are different.

Saving a file means writing the current file contents to disk in the editor. Committing means recording, in repository history, a meaningful bundle chosen from those saved changes.

git status Asks About the Current State¶

The command you usually check first when doing Git work is git status.

1

git status

This command answers the following questions.

• Which files were modified?
• Is there any new file?
• Is there any file already chosen for this commit?
• What is the current branch?

Here, understand git status as "the command that asks what state the current workspace is in."

git add Is the Act of Choosing Files¶

git add does not mean that the file is immediately and permanently saved. It means placing the changes that should be included in this commit into the staging area.

1

git add docs/chapter-14/section-01.md

The key point is, "choose which changes go into this record." Even if many files changed, you do not need to put them all into one commit. If the purposes differ, it is easier to read later if you commit them separately.

For example, the following two tasks should be recorded separately whenever possible.

If both changes go into one commit, it becomes harder later to trace "why was this CSS changed?"

git commit Means Naming a Bundle of Changes¶

git commit leaves the staged changes in repository history.

1

git commit -m "docs(part2): add git version control introduction"

A commit message is not just a memo. It is the title that tells a later reader of the history "what this change is."

A good commit message usually satisfies the following conditions.

• It lets you tell what changed.
• It avoids expressions that are too broad.
• It shows the purpose of the change rather than just listing a file name.
• It still makes sense later when read in git log.

A bad example is the following.

1

git commit -m "update"

This message does not tell you what was updated.

git log Is the Command That Reads Change History¶

Once commits accumulate, you can check the history with git log.

1

git log --oneline

This command shows the commit list briefly. Here, understand it as "the list that shows in what order this project changed."

In a learning-document project, git log helps with the following questions.

• When was this section added?
• In which commit was the table of contents changed?
• With which manuscript was a certain image file added?
• What changes entered before deployment?

Why Git Matters in a Document Project¶

A document project is not just a finished document. It is the result of a learning process. The manuscript, research notes, example code, images, and deployment settings all change together. In particular, from Part 3 onward, even with the same data, preprocessing, baselines, thresholds, and evaluation tables begin to change together. In that sense, Git is closer to an experiment comparison record than to a cabinet for storing final answers.

Git lets you leave behind the following relationships.

From this perspective, Git is not a tool only for developers. As documents grow, evidence increases, and practice code accumulates, Git becomes the tool that manages the history of learning changes.

The Minimum Habits to Use with Git¶

You do not need to know every Git command from the beginning. In a project that handles documents and practice examples together, even the following habits help a lot.

1. Check the state with git status before and after work.
2. Put into one commit only changes that share one purpose.
3. Write the purpose of the change in the commit message.
4. Check the relationship between generated files and source files together.
5. Separate work that changes deployment settings from work that writes the manuscript.

These habits are needed again in P2-14.2 when you study the flow of branches, authoring branches, and deployment branches.

Case Study¶

Case 1. How Should You Explain the Day When the Manuscript and Images Changed Together?¶

Suppose a document writer edited the manuscript of one section, changed the example code together with it, and also changed the plot images recreated from that code. In the person's head, this is still the same task, but after several days it can become blurry why those files changed together.

At that point, Git works not as a simple storage box but as a record that groups reasons for change. If the manuscript Markdown, image-generation code, output images, and table-of-contents edits all belong to one purpose, strengthening the plot explanation, then that purpose can be left behind together with a commit message.

This case also shows why git add and git commit are separated. First you choose the changes that belong in this record. Then you give that bundle a name and leave it in history. Only then can you explain later what changed, and why.

In other words, what matters in Git basics is not memorizing many commands. It is developing the sense of grouping changes into meaningful units of explanation. Only with that sense does the history stay readable in a project where documents, code, and images move together.

Checklist¶

• Can you explain the difference between saving a file and making a Git commit?
• Can you distinguish the working tree, staging area, and repository?
• Can you state the roles of git status, git add, git commit, and git log?
• Can you explain why one commit should carry one purpose?
• Can you explain why Git is needed as a learning-record management tool in a document project?
• Can you explain that Git is a change-history management tool, and that commits let you track the connection among manuscripts, code, images, and research notes.

Sources and References¶

• Scott Chacon and Ben Straub, Pro Git 2nd Edition: About Version Control, Git documentation, checked on 2026-07-20. https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control Basis for describing version control as a record of file changes over time and a way to recover specific versions.
• Git project, git-status Documentation, checked on 2026-07-20. https://git-scm.com/docs/git-status Direct reference for explaining that git status reports working tree, index, and untracked-file state.
• Git project, git-commit Documentation, checked on 2026-07-20. https://git-scm.com/docs/git-commit Direct reference for explaining that git commit records the current index contents with a log message as a new commit.