Skip to content

Commit d91bc08

Browse files
brabojclaude
andcommitted
docs: clarify push-to-non-bare explanation
Make explicit that a push only updates the branch reference, not the working tree. Show the broken state with HEAD vs working tree diagram. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent bf9f555 commit d91bc08

1 file changed

Lines changed: 19 additions & 13 deletions

File tree

chapters/recipes/bare-repositories.md

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -117,25 +117,31 @@ $ git push /tmp/dev-alice main
117117
remote: error: refusing to update checked out branch: refs/heads/main
118118
```
119119

120-
To understand why, imagine two developers — Alice and Bob — where
121-
Alice's repository is non-bare and Bob tries to push to it:
120+
To understand why, remember that a push only updates the branch
121+
reference inside `.git/` — it does **not** touch the working tree.
122+
These are two separate operations, and only the first one happens.
123+
124+
Imagine Alice and Bob, where Alice's repository is non-bare and Bob
125+
tries to push to it:
122126

123127
1. Alice clones a repository and checks out `main`. Her working tree
124128
has the files from commit `A`.
125129
2. Alice edits `report.txt` but has not committed yet.
126-
3. Bob pushes a new commit `B` to Alice's repository. Git updates
127-
Alice's `main` branch to point to `B`.
128-
4. Now Alice's branch says `B`, but her working tree still has the
129-
files from `A` — plus her uncommitted edits. Git has no way to
130-
merge Bob's changes into Alice's working tree automatically.
131-
5. If Alice runs `git status`, she sees phantom differences — her
132-
files look changed relative to `B`, even though she never touched
133-
them. Her real edits are mixed in with the noise, and she could
134-
lose work.
130+
3. Bob pushes a new commit `B` to Alice's repository. The push
131+
updates the reference `.git/refs/heads/main` to point to `B`
132+
but Alice's working tree is not updated. Her files on disk are
133+
still from commit `A`, plus her uncommitted edits.
134+
4. Alice's repository is now in a broken state:
135+
- `HEAD``main` → commit `B` (moved by the push)
136+
- Working tree → files from commit `A` + uncommitted edits (untouched)
137+
5. If Alice runs `git status`, Git compares her working tree against
138+
commit `B`. Every file Bob changed shows up as a difference —
139+
mixed in with Alice's real edits. She cannot tell which changes
140+
are hers and which are artifacts of the branch moving under her.
135141

136142
Git prevents step 3 entirely. A bare repository avoids this problem
137-
because there is no working tree and no one editing files in it —
138-
updating the branch is always safe.
143+
because there is no working tree — updating the branch reference is
144+
always safe when there are no files to desynchronize.
139145

140146
If you need to accept pushes on a non-bare repository (rare), you
141147
can enable it:

0 commit comments

Comments
 (0)