Let’s take it apart.

Setup

Make a throwaway repo so we can poke at it safely:

mkdir git-internals && cd git-internals
git init -b main
echo "hello" > hello.txt
git add hello.txt
git commit -m "first commit"

Now look inside:

ls .git

You’ll see things like HEAD, config, index, objects/, and refs/. We’ll go through the important ones.

Objects: the actual data

Git stores everything as objects in .git/objects. There are four kinds:

• blob: the contents of a file (just the bytes, no name)
• tree: a directory listing (names, permissions, and pointers to blobs and other trees)
• commit: a snapshot (a pointer to one tree, parent commits, author, message)
• tag: an annotated tag (a pointer to an object, plus a message)

Every object is named by the hash of its contents. That’s why Git is called a content-addressable store: the address is the content’s fingerprint.

Finding our file

Ask Git what hash “hello\n” would get as a blob:

echo "hello" | git hash-object --stdin

ce013625030ba8dba906f756967f9e9ca394464a

You’ll get this exact hash on any machine, in any repo. Same content, same hash, always.

Now find it on disk. Git splits the hash: the first two characters are a folder, the rest is the file name:

ls .git/objects/ce/

There it is. The file is zlib-compressed, so cat shows garbage. Git can read it for us:

git cat-file -t ce0136   # type
git cat-file -p ce0136   # contents

blob
hello

Or decompress it yourself with Python to see the raw format:

python3 -c "import zlib,sys; print(zlib.decompress(open(sys.argv[1],'rb').read()))" .git/objects/ce/013625030ba8dba906f756967f9e9ca394464a

b'blob 6\x00hello\n'

That’s the entire format: the type, a space, the size in bytes, a null byte, then the content. The hash is SHA-1 of exactly that string.

Walking from a commit down to a file

Start at the latest commit:

git cat-file -p HEAD

tree aaa96ced2d9a1c8e72c56b253a0e2fe78393feb7
author ...
committer ...

first commit

Follow the tree:

git cat-file -p aaa96c

100644 blob ce013625030ba8dba906f756967f9e9ca394464a    hello.txt

That’s the whole chain: commit → tree → blob. A commit doesn’t store differences; it points to a full snapshot. Git saves space because unchanged files keep the same hash, so every commit just points to the same blob again.

(Your commit hash will differ from mine, because a commit includes your name and the exact time. The tree and blob hashes will match, because they depend only on file names and contents.)

Refs: names for hashes

Nobody wants to type 40-character hashes. Refs are files that hold them:

cat .git/refs/heads/main

That’s it. A branch is a text file containing a commit hash. Creating a branch is writing one small file. That’s why branches in Git are so cheap.

And HEAD?

cat .git/HEAD

ref: refs/heads/main

HEAD usually points to a branch, which points to a commit. When you’re in “detached HEAD” state, HEAD contains a commit hash directly instead.

If a branch seems to be missing from refs/heads, check .git/packed-refs. Git bundles refs into that one file to save space.

Packfiles: how Git stays small

Storing every version of every file as a separate compressed object would get big. So Git periodically packs objects into .git/objects/pack/, storing similar objects as deltas (differences) against each other.

git gc
git count-objects -v

Loose objects disappear into a .pack file with a matching .idx index. To peek inside:

git verify-pack -v .git/objects/pack/pack-*.idx | head

Interesting detail: this is the only place Git uses deltas. Your history is modeled as snapshots; deltas are just a storage optimization underneath.

The index: the staging area is a file

git add writes to .git/index, a binary file listing what the next commit will contain. You can see it in readable form:

git ls-files --stage

100644 ce013625030ba8dba906f756967f9e9ca394464a 0	hello.txt

The staging area isn’t a concept. It’s a file.

The reflog: your safety net

Every time HEAD or a branch moves, Git writes a line to .git/logs/:

git reflog

This is how you recover from almost anything: a bad reset, a deleted branch, a rebase gone wrong. Find the hash from before the mistake and:

git branch rescue <hash>

Unreachable objects are only deleted by garbage collection after a grace period (two weeks by default for loose objects). Reflog entries last 90 days, but only 30 for commits that are no longer on any branch, which is what a bad reset or rebase leaves behind. You have time.

Build a commit with no porcelain

For the grand finale, make a commit using only low-level commands:

echo "built by hand" | git hash-object -w --stdin
# note the hash, then:
git update-index --add --cacheinfo 100644 <blob-hash> handmade.txt
git write-tree
# note the tree hash, then:
git commit-tree <tree-hash> -p HEAD -m "a commit made by hand"
# note the commit hash, then:
git update-ref refs/heads/main <commit-hash>

Run git log. Your hand-built commit is there, indistinguishable from any other. (git status will call handmade.txt deleted, because so far the file only exists in the repo. git restore handmade.txt writes it out.) Every friendly Git command is built from pieces like these.

Things you should know

• Don’t edit .git by hand in real repos. Explore in a throwaway one.
• SHA-256 repos exist. Git supports git init --object-format=sha256, which gives 64-character hashes. The structure is the same.
• Refs won’t always be files. Git 3.0 will switch new repos to the reftable format, and you can try it today with git init --ref-format=reftable. There, branches live in binary tables under .git/reftable/, and .git/HEAD just says ref: refs/heads/.invalid. Commands like git branch and git rev-parse work the same either way.
• Hashes include everything. Change one byte of a file, one character of a commit message, or a timestamp, and the hash changes, along with every commit after it. That’s why rewriting history changes all later commit IDs.

Closing thought

Once you’ve seen that a branch is a text file and a commit is a pointer to a snapshot, most of Git’s “weird” behavior stops being weird. It’s a database. Now you can read it.

You could read them all. Or you could let Git find the guilty one in about nine steps.

The idea: binary search through history

git bisect takes two points: a commit where things were good and one where they’re bad. It checks out the commit halfway between and asks you which it is. Then it throws away the half that can’t contain the bug and repeats.

Each step halves the search. 400 commits takes at most 9 steps. 10,000 commits takes at most 14.

Manual bisect

git bisect start
git bisect bad                 # the current commit is broken
git bisect good v2.3.0         # this tag was fine

Git checks out a commit in the middle and tells you roughly how many steps are left. Test it, then tell Git:

git bisect good    # this one works
# or
git bisect bad     # this one is broken

Repeat until Git prints:

a1b2c3d is the first bad commit

When you’re done, go back to where you started:

git bisect reset

You can also give both endpoints up front:

git bisect start HEAD v2.3.0

The real magic: git bisect run

If you can write a script that tells good from bad, Git will do the whole search without you:

git bisect start HEAD v2.3.0
git bisect run ./check.sh

Git checks out each candidate commit, runs your script, and reads its exit code:

Your test suite is often the script already:

git bisect run pytest tests/test_login.py
git bisect run cargo test parse_header
git bisect run npm test

Writing a good check script

The script should test only the bug you’re hunting. A full test suite may fail for unrelated reasons partway through history.

#!/bin/sh
# check.sh: exit 0 if the bug is absent, 1 if present, 125 if we can't tell

# If it doesn't build, we can't test this commit. Skip it.
make >/dev/null 2>&1 || exit 125

# The actual check
./app --version | grep -q "expected output" && exit 0 || exit 1

A few tips:

• Use 125 for “can’t test.” Commits that don’t compile, or that predate the feature entirely, should be skipped, not marked bad. Otherwise Git blames the wrong commit.
• Keep the script outside the repo, or untracked. Bisect checks out old commits, and an old commit might not have your script, or might have an older version of it.
• Make it fast. It runs once per step.
• Make it deterministic. A flaky test sends the search in the wrong direction and gives a confident, wrong answer.

Useful extras

Skip a commit by hand:

git bisect skip

See or replay the session. If you mark a commit wrong, save the log, edit out the mistake, and replay it:

git bisect log > bisect.log
# edit bisect.log
git bisect reset
git bisect replay bisect.log

Visualize what’s left:

git bisect visualize --oneline

Hunt for things that aren’t bugs. “Good” and “bad” are just labels. You can rename them:

git bisect start --term-old=fast --term-new=slow
git bisect fast v2.3.0
git bisect slow HEAD

Now you can find the commit where something got slow, or the commit where a feature first appeared.

Ignore merged-in side branches. On a repo with many merges, --first-parent only follows the main line of history:

git bisect start --first-parent

Things you should know

• Bisect needs a clean working tree. Commit or stash your changes first.
• It finds the first bad commit, not the cause. Sometimes the “first bad commit” just exposed a bug that was already there. Read the diff before blaming anyone.
• Small commits make bisect better. If the guilty commit changed 3,000 lines, knowing which commit it was doesn’t help much. Another reason to commit in small, focused steps.

Closing thought

The next time you catch yourself scrolling through git log trying to guess when something broke, stop. Write a ten-line script, run git bisect run, and go get a coffee.

Most people do one of these:

• git stash, switch branches, fix, switch back, git stash pop, pray.
• Commit a “WIP” mess they’ll have to clean up later.
• Clone the whole repo again into another folder.

There’s a better option that has been in Git since 2015: worktrees.

What a worktree is

A normal repo has one working directory: the folder where your files live. A worktree is an extra working directory attached to the same repo. Each one can have a different branch checked out, and they all share the same history, objects, and remotes.

It’s like a second clone, except:

• It’s instant. Nothing is downloaded or copied.
• It uses almost no extra disk space for history.
• A commit made in one worktree is immediately visible from the others.

The basics

Create a worktree for an existing branch:

git worktree add ../myproject-hotfix hotfix

Now ../myproject-hotfix is a full working folder with the hotfix branch checked out. Your original folder is untouched, half-finished feature and all.

Create a worktree and a new branch at the same time:

git worktree add -b fix-login ../myproject-fix-login main

That makes a new branch fix-login starting from main, checked out in a new folder.

See all your worktrees:

git worktree list

When you’re done, remove it:

git worktree remove ../myproject-hotfix

If you deleted a worktree folder by hand instead, clean up Git’s records of it:

git worktree prune

Daily uses

Emergency fixes without disruption. The scenario above. Your feature work stays exactly where you left it.

Reviewing a pull request while you keep working. Check out the PR branch in its own worktree, run it, test it, and delete the folder when you’re done.

Comparing behavior side by side. Run the old version and the new version at the same time in two terminals.

Long builds. Kick off a slow build or test suite in one worktree and keep coding in another. Your edits won’t change files out from under the running build.

Running AI coding agents in parallel. Give each agent its own worktree so they don’t overwrite each other’s changes.

Things you should know

One branch, one worktree. Git won’t let you check out the same branch in two worktrees at once, because commits in one would confuse the other. If you try, you’ll get an error. (There’s a --force flag, but you almost never want it.)

Some things are shared, some aren’t. Commits, branches, tags, remotes, config, and the stash are shared across all worktrees. The working files, the index (staging area), and HEAD are per-worktree.

Untracked files don’t come along. A new worktree starts clean. Your .env, node_modules, or build folders from the main worktree won’t be there. You’ll need to reinstall dependencies or copy config.

Keep worktrees outside the main folder. Putting a worktree inside your main working directory makes tools, file watchers, and searches see duplicate files. A sibling folder (../project-something) is the usual convention.

Lock worktrees on removable drives. If a worktree lives on a USB drive or network share that isn’t always mounted, lock it so prune doesn’t delete its records:

git worktree lock ../usb-worktree --reason "on external drive"

A bare-repo trick

Some people go further: they clone a repo as bare (no working files at all) and do everything through worktrees:

git clone --bare git@github.com:you/project.git project/.bare
cd project
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch
git worktree add main
git worktree add feature-x

The git config line matters. A bare clone doesn’t set up remote-tracking branches, so without it, git fetch quietly never updates them.

Now every branch you work on is a tidy subfolder of project/. It takes a little getting used to, but it makes “which branch am I on?” a question your file manager answers.

Closing thought

git stash is fine for thirty seconds. For anything longer, stop juggling and give each branch its own folder.

What it is

.gitattributes is a plain text file that assigns attributes to paths. Each line is a pattern followed by one or more attributes:

*.sh    text eol=lf
*.png   binary
docs/** linguist-documentation

The patterns work much like .gitignore, with two catches. Negation (!pattern) isn’t allowed. And a directory pattern like vendor/ does not apply to the files inside it, so you need vendor/**.

Each attribute can be in one of four states:

• Set: text
• Unset: -text
• Set to a value: eol=lf
• Unspecified: !text, which resets it to as if you never mentioned it

Where it lives

Git reads attributes from several places, from highest priority to lowest:

1. .git/info/attributes: local to your clone and never committed. Good for personal rules.
2. .gitattributes files in the repo. A file in a subdirectory overrides one in a parent directory.
3. Your global file (set with core.attributesFile, usually ~/.config/git/attributes).
4. The system-wide file.

When a file behaves strangely, ask Git what it thinks:

git check-attr -a path/to/file

1. End the line-ending wars

This is the reason most people should add a .gitattributes today. Windows uses CRLF, everything else uses LF, and without rules you end up with diffs where every line “changed.”

* text=auto
*.sh  text eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf

text=auto lets Git detect text files and store them with LF in the repo. The eol= rules pin specific file types, which matters for shell scripts that break with CRLF and batch files that expect it.

Know this: adding these rules doesn’t fix files that are already committed. Run this once and commit the result:

git add --renormalize .

To see the current line-ending state of every file:

git ls-files --eol

2. Mark binaries as binary

*.png  binary
*.jpg  binary
*.zip  binary

binary is a built-in macro that expands to -text -diff -merge. Git won’t try to convert line endings, show a text diff, or attempt a text merge. That last one saves you from corrupted files after a merge that “succeeded.”

3. Hunk headers that actually help

When you run git diff, each hunk starts with a line like @@ -12,7 +12,8 @@, followed by some context Git guessed at. Often that guess is useless. Tell Git the language and it names the enclosing function or class instead:

*.py   diff=python
*.rs   diff=rust
*.go   diff=golang
*.java diff=java
*.md   diff=markdown
*.tex  diff=tex

These drivers are built in. There’s nothing to install. The Markdown one shows the nearest heading, which is great for docs.

4. Diff files that aren’t text

With a textconv driver, Git runs a command that turns a binary file into text, then diffs that text.

*.png  diff=exif
*.pdf  diff=pdf
*.docx diff=docx

git config --global diff.exif.textconv exiftool
git config --global diff.docx.textconv "pandoc --from=docx --to=plain"

Git appends the file path to the command, and the command must print text to stdout. exiftool and pandoc already do that. pdftotext doesn’t; by default it writes a .txt file next to the input. Wrap it in a tiny script:

#!/bin/sh
# save as ~/bin/pdf2txt and chmod +x it
pdftotext -layout "$1" -

git config --global diff.pdf.textconv pdf2txt

Now git diff on an image shows which metadata changed, and git log -p on a Word doc or PDF shows actual prose changes. Add git config --global diff.pdf.cachetextconv true so Git doesn’t reconvert unchanged files every time.

5. Silence noise you don’t care about

package-lock.json -diff
Cargo.lock        -diff
*.min.js          -diff

The files are still tracked and versioned normally. git diff just prints “Binary files differ” instead of four thousand lines of dependency churn.

6. Merge strategies per file

CHANGELOG.md  merge=union

union keeps the lines from both sides instead of creating a conflict. It’s perfect for append-only files like changelogs or lists of contributors. It’s dangerous for anything where order or structure matters, like code or JSON.

You can also keep your own version of a file on merge:

config/local.yml merge=ours

git config merge.ours.driver true

Know this: a merge driver only runs when both branches changed the file. If only the other branch touched it, Git takes their version cleanly and your driver never runs. Plenty of people have been surprised by this.

7. Clean and smudge filters

This is the most powerful feature in the file. A filter has two halves:

• clean runs when a file is staged, transforming the working copy into what gets stored.
• smudge runs on checkout, transforming the stored version back into your working copy.

*.ipynb filter=nbstrip

git config filter.nbstrip.clean "jupyter nbconvert --clear-output --to notebook --stdout --stdin"
git config filter.nbstrip.smudge cat
git config filter.nbstrip.required true

Now notebook outputs never get committed, but you keep them locally.

Real-world tools built on filters:

• Git LFS stores large files elsewhere and commits small pointers: *.psd filter=lfs diff=lfs merge=lfs -text
• git-crypt transparently encrypts files in the repo and decrypts them on checkout
• nbstripout does the notebook trick above

Know this: filter definitions live in Git config, not in the repo. .gitattributes only says “use the filter named X.” Every person who clones the repo has to set up the filter themselves. This is on purpose: if a repo could define commands that run automatically on checkout, cloning a stranger’s repo would be a security risk. Document your filters in the README.

8. Shape your release archives

git archive builds a tarball or zip of your repo. Attributes control what goes in it:

tests/         export-ignore
.github/       export-ignore
.gitattributes export-ignore
VERSION        export-subst

export-ignore leaves files out of release archives. GitHub’s “Download ZIP” and release source tarballs respect this too. It’s also one of the few attributes where a directory pattern like tests/ works, because git archive checks each directory as it walks the tree.

export-subst expands placeholders at archive time. Put this in VERSION:

$Format:%H$ $Format:%cd$

The archive will contain the real commit hash and date.

9. The GitHub extras

GitHub reads a set of linguist-* attributes that change how your repo is displayed:

vendor/**      linguist-vendored
dist/**        linguist-generated
docs/**        linguist-documentation
*.nx           linguist-language=Rust
scripts/*.txt  linguist-detectable

• linguist-vendored and linguist-documentation exclude files from the language bar.
• linguist-generated also collapses those files in pull request diffs. For generated code, lockfiles, or build output, this makes reviews much faster.
• linguist-language fixes misdetection, or lets a custom language borrow another’s highlighting.
• linguist-detectable forces a language to count toward the stats when it normally wouldn’t.

10. Lesser-known attributes

whitespace sets per-file rules for what git diff --check flags:

*.md whitespace=-trailing-space
*.py whitespace=trailing-space,tab-in-indent

Markdown uses two trailing spaces as a line break, so you don’t want those flagged there.

working-tree-encoding stores UTF-16 files as UTF-8 in the repo so they diff properly, then converts them back on checkout:

*.ps1 working-tree-encoding=UTF-16LE eol=crlf

Only use it on files that really are UTF-16. With this line, git add refuses a .ps1 saved with a byte order mark (declare UTF-16LE-BOM for those) and one saved as UTF-8, which is what most editors write today.

-delta skips delta compression for huge binaries that don’t compress well anyway, which speeds up packing:

*.mp4 -delta

ident expands $Id$ in a file to $Id: <blob hash>$ on checkout. It’s old-school, but handy for embedding a file’s exact version.

lockable works with Git LFS file locking. Files are checked out read-only until you lock them, which prevents two people from editing the same unmergeable file:

*.psd lockable

11. Macros

In the top-level .gitattributes only, you can define your own bundles of attributes:

[attr]lockfile -diff linguist-generated

package-lock.json lockfile
yarn.lock         lockfile
Cargo.lock        lockfile

One name, one place to change it later.

Know this: don’t put merge=ours in a macro like this. When both branches add a dependency, the merge succeeds without a conflict and the lockfile quietly loses the other branch’s entries. Regenerate lockfiles after a merge instead.

A sane starter file

If you take one thing from this post, drop this into your next project:

# Normalize line endings
* text=auto

# Scripts that care about endings
*.sh  text eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf

# Better diff hunk headers
*.py diff=python
*.md diff=markdown
*.rs diff=rust

# Binaries
*.png binary
*.jpg binary
*.gif binary
*.ico binary
*.zip binary
*.pdf binary

# Quiet noisy files
*.lock            -diff
package-lock.json -diff

# Keep release archives clean
.github/        export-ignore
.gitattributes  export-ignore

Closing thought

.gitignore tells Git what to leave out. .gitattributes tells Git how to understand everything you keep. It’s a few lines of text that fix line-ending chaos, make diffs readable, prevent merge disasters, and shape what your users download. Most repos never touch it. Now yours can.