Skip to content

Commit bf9f555

Browse files
brabojclaude
andcommitted
docs: step-by-step explanation of why pushing to non-bare fails
Replace one-sentence summary with Alice-and-Bob scenario showing how a push would desync the working tree and cause lost work. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 7ea2d73 commit bf9f555

1 file changed

Lines changed: 19 additions & 4 deletions

File tree

chapters/recipes/bare-repositories.md

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

120-
Git refuses because the push would change the branch that the working
121-
tree is based on, leaving the working tree out of sync. This is
122-
exactly why central repositories are bare — they have no working tree
123-
to desynchronize.
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:
122+
123+
1. Alice clones a repository and checks out `main`. Her working tree
124+
has the files from commit `A`.
125+
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.
135+
136+
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.
124139

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

0 commit comments

Comments
 (0)