Repositories, Working Tree, Index, HEAD, and the File Lifecycle: Concepts, Architecture, and Mental Model

1. The problem — “my file changed” is not one Git state

Chapter 03 showed that committed history is built from immutable objects and movable refs. Everyday Git work happens in front of that object database, where the same path can have three different versions at once: the version recorded by HEAD, the version prepared in the index, and the version currently on disk in the working tree.

Most accidental data loss and many bad commits begin when a command is chosen by vague intent—“undo this,” “save this,” “remove this”—instead of by the layer that should change. This chapter replaces those verbs with a state model you can inspect before and after every operation.

2. Four layers you must keep separate

3. State-flow mental model

flowchart TD
H[HEAD commit tree] -->|git restore --staged path| I[Index: proposed next snapshot]
H -->|commit supplies baseline| I
I -->|git restore path| W[Working tree]
W -->|git add path| I
I -->|git commit| C[New commit]
C -->|current branch moves| H2[New HEAD commit]
W -. untracked path .-> U[Not in index]
G[Ignore rules] -. suppress ordinary untracked reporting .-> U

The arrows are deliberately directional. git add copies selected working-tree content into the index; it does not “send a file to GitHub.” A normal git commit records the index as a new commit and advances the current branch. git restore can copy content toward the working tree or, with --staged, reset index content from a source such as HEAD.

4. The index is a proposed next snapshot, not a waiting room

Calling the index a “staging area” is convenient but incomplete. It contains path entries, modes, and object IDs representing the exact content Git would normally place into the next commit. That is why a file can be staged and then modified again: the index keeps the staged version while the working tree moves on.

git status --short
git diff
git diff --staged
git ls-files --stage

The first diff compares working tree to index. The staged diff compares index to HEAD. Together they explain the two columns in short status.

5. File states are comparisons, not permanent labels

• Untracked: exists in the working tree but has no index entry and is not ignored.
• Ignored: normally untracked and matched by an active exclude rule; tracked files do not become untracked merely because a pattern later matches them.
• Modified: working-tree content differs from the index, or an index entry differs from HEAD, depending on which comparison you mean.
• Staged: the index differs from HEAD for that path.
• Committed: content is reachable through a commit snapshot such as HEAD.
• Deleted: a tracked path is absent from the working tree or staged absent from the next snapshot.
• Renamed: status/diff may report a rename when comparing snapshots and finding sufficiently similar content; Git does not create a special rename object.

6. HEAD: symbolic in normal branch work, direct when detached

Normally HEAD is a symbolic ref pointing at the current branch—for example, refs/heads/trunk. The branch then points at a commit. In detached HEAD state, HEAD identifies a commit without being attached to a local branch name.

git symbolic-ref -q HEAD
git rev-parse --verify HEAD
git status --short --branch

git symbolic-ref -q HEAD succeeds when HEAD is symbolic and exits non-zero when detached. Detached HEAD is valid for inspection and experiments, but new commits can become unreferenced after you switch away unless you create a branch/tag to retain them.

7. Pathspecs select paths; revisions select history

A pathspec is Git's syntax for limiting commands to paths. It is not identical to shell globbing. The shell may expand an unquoted wildcard before Git ever sees it, while a quoted pathspec is interpreted by Git.

git status -- "docs/*.md"
git diff HEAD -- README.md
git add -- "src/*.py"

The standalone -- means “stop parsing revisions/options; what follows is path selection.” It is especially valuable when a path resembles a branch, tag, revision, or option.

8. Inspection ladder before mutation

git rev-parse --show-toplevel
git status --short --branch
git symbolic-ref -q HEAD
git rev-parse --verify HEAD
git diff
git diff --staged
git ls-files --stage
git ls-tree -r HEAD --name-only

This ladder answers, in order: which repository, which branch/HEAD state, what the working tree changed relative to the index, what the index changed relative to HEAD, what is actually in the index, and what HEAD records.

9. DevOps connection — pipelines act on exact layers too

CI scripts that generate files, stage release metadata, or inspect a checkout must know whether they are reading committed source, dirty working-tree content, or staged-but-uncommitted state. Packaging a dirty working tree when the policy requires an exact commit is a provenance error; committing unintended generated files because git add . was used casually is a release-quality error.

10. Knowledge check

11. Summary

Everyday Git is a controlled movement among working tree, index, HEAD, and immutable objects. The index is the exact proposed next snapshot; status and diff are comparisons among layers; HEAD can be symbolic or detached; pathspecs control which paths a command touches.

Authoritative references

• git-status
• Git glossary
• git-diff
• git-ls-files