Repositories & the Working Tree

The three-place mental model

When you ask Git what changed, it is not comparing a file against one single truth. It is comparing three places: the last committed snapshot, the staged snapshot you are preparing, and the files currently on disk. Most beginner confusion comes from mixing those places together.

The important word is snapshot. A commit is not a running diary of every keystroke. It is a recorded project state. The index exists so you can build that state deliberately, even when your working tree contains extra experiments, debugging notes, or half-finished edits.

Repository versus working tree

A working tree is the ordinary directory tree where your project files appear. If you open README.md, change a function, or delete a generated file, you are changing the working tree.

That difference explains why deleting a file from your editor does not instantly erase history. You removed a file from the working tree. The repository still has previous snapshots until you intentionally stage and commit the removal. It also explains why a folder can contain project files but not yet be a Git repository: without .git, Git has nowhere to store history or compare states.

git rev-parse --is-inside-work-tree
git status

If the first command prints true, Git found repository metadata above or at the current directory. If git status says the directory is not a Git repository, you are outside a work tree or inside a directory that has not been initialized.

What lives in .git

The .git directory is not a backup folder full of duplicate project files. It is Git's database and control center. You rarely edit it by hand, but knowing the landmarks makes Git feel less mysterious.

Objects, commits, and HEAD

At a high level, Git is a content-addressed database. Content goes in; Git computes an object ID from that content; later, other objects and names can point to that ID. You do not need internals fluency for daily work, but the basic object shapes matter.

HEAD is your current position. In normal branch-based work, HEAD points to a branch, and the branch points to the latest commit on that branch. When you commit, Git writes a new commit object from the index, then moves the branch forward so HEAD sees the new snapshot.

git status --short --branch
git log --oneline -1
git rev-parse --abbrev-ref HEAD

That last command usually prints your branch name. In a detached-HEAD state it prints HEAD, which means you checked out a commit directly rather than a branch name. Detached HEAD is not automatically bad, but it changes where new commits will be attached.

The index and staging area

The index is the most important Git idea that most tools hide. It is a file inside .git that records what the next commit will look like. The phrase staging area is the friendly name for the same idea.

git add does not mean "start tracking forever" in every situation. More generally, it updates the index using content from the working tree. If a file is new, that can make the file tracked. If a file is already tracked, it stages the current version. If a tracked file was deleted, git add can stage that deletion.

git status
git add docs/intro.md
git status

After the git add, Git may still report changes in the same file under "not staged" if you edited it again. That is not a contradiction. The index contains the version you staged; the working tree contains a newer version. One path can be both staged and modified at the same time because Git is comparing different pairs of snapshots.

Tracked and untracked files

A tracked file is known to Git because it is in the last commit, in the index, or both. An untracked file exists in the working tree but is not part of Git's known snapshots. Git sees it, but it will not include it in a commit unless you stage it.

git status --short
# ?? notes.txt       untracked
#  M app.js          modified in working tree
# M  README.md       modified in index
# MM package.json    staged version plus newer unstaged edits

This is why git status is the safest habit in early Git work. It tells you which files are untracked, which changes are staged for commit, and which tracked files have working-tree edits that are not staged yet.

Init versus clone

There are two common ways to get a local repository. git init turns an existing directory into a new repository. git clone copies an existing repository from somewhere else and checks out a working tree for you.

cd my-project
git init
git add README.md
git commit -m "Initial commit"

git clone https://github.com/libgit2/libgit2
cd libgit2
git status

Both routes produce a repository and a working tree on your machine. The difference is the source of the history. With init, the first commit is yours to create. With clone, the object database, refs, remote configuration, and checked-out files are copied from an existing project.

Common pitfalls

Worked examples

git status --short
#  M app.js
git add app.js
git status --short
# M  app.js

git status --short
# MM README.md

touch notes.txt
git status --short
# ?? notes.txt
git add notes.txt
git status --short
# A  notes.txt

cd recipe-site
git init
git status --short
# ?? index.html
# ?? styles.css

git clone https://github.com/libgit2/libgit2
cd libgit2
git status --short --branch