Git Architecture: The Three-Tree Model (Working Tree, Index & Repository)

The single most important concept to master in Git is the Three-Tree Architecture. Developers who struggle with Git usually do so because they treat it like Dropbox or Google Drive. Once you grasp how Git separates your files across three distinct states, every Git command suddenly makes intuitive sense.

Figure 4.1: The Three Trees of Git — Physical Working Tree, Staging Index (.git/index), and Local Repository (.git/objects).

What are the Three Trees?

In Git terminology, a "tree" here refers to a collection of files and directory structures. Git manages your files across three logical areas:

1. The Working Directory (Working Tree)

The Working Directory is the actual physical folder on your computer's hard drive or SSD where you view, edit, and create files using your code editor (like VS Code, IntelliJ, or Notepad). It is the only area visible to standard operating system file browsers.

• Files here can be in an untracked state (newly created files Git doesn't know about yet) or a modified state (tracked files you have changed since the last commit).
• Changes in your working directory are transient and not protected by Git until you stage them.

2. The Staging Area (The Index / Cache)

The Staging Area (technically referred to in Git source code as the Index) is a binary file stored at .git/index. It acts as an intermediate holding zone and a preview of your proposed next commit snapshot.

• When you run git add [file], Git compresses the file's current content into a SHA-1 blob object in .git/objects/ and records its path and permissions in the Index.
• The staging area gives you full granular control over what changes get grouped together into a commit. If you edited 5 files for two different bug fixes, you can stage 2 files for Bug A, commit them, and then stage the remaining 3 files for Bug B.

3. The Local Repository (.git / HEAD)

The Local Repository is the permanent historical database stored inside the hidden .git/ directory at the root of your project. When you run git commit, Git takes the exact snapshot represented by the Staging Area, creates an immutable commit object, and updates the branch reference pointer (such as refs/heads/main) and HEAD to point to this new commit.

• Commits stored in the repository are permanent and cryptographically secured.
• Even if you delete all files in your Working Directory, you can reconstruct the entire project in a split second from the Local Repository!

The 4 Life-Cycle States of a File

Every file in your working folder belongs to one of four states:

Transitioning Files Across the Trees: A Concrete Example

Let's observe the three trees in action through a standard developer workflow:

# 1. Edit a file in Working Directory
$ echo "const API_URL = 'https://api.veewom.com';" >> config.js
# State: config.js is MODIFIED in Working Tree. Index and HEAD are untouched.

# 2. Stage the file into the Index
$ git add config.js
# State: config.js is now STAGED. Git created a blob object in .git/objects.

# 3. Snapshot the Index permanently into the Repository
$ git commit -m "feat: configure Veewom production API endpoint"
# State: Git created a tree and commit object. HEAD points to this new commit.
# All three trees (Working Tree, Index, HEAD) are now in 100% sync!

git ls-files --stage