@@ -117,25 +117,31 @@ $ git push /tmp/dev-alice main
117117remote: 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
1231271 . Alice clones a repository and checks out ` main ` . Her working tree
124128 has the files from commit ` A ` .
1251292 . 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
136142Git 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
140146If you need to accept pushes on a non-bare repository (rare), you
141147can enable it:
0 commit comments