Skip to content

Commit 044a643

Browse files
brabojclaude
andcommitted
docs: explain why bare repos exist and why pushing to non-bare fails
Add paragraph connecting the structural difference to the practical consequence — bare repos accept pushes because there is no working tree to desynchronize; non-bare repos reject pushes to protect the checked-out files. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent dbf62ad commit 044a643

1 file changed

Lines changed: 13 additions & 0 deletions

File tree

chapters/02-building-blocks.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,19 @@ The `.git` folder contains the same structure as a bare repository.
8888
The difference is that a non-bare repository also has a working tree
8989
next to it — the place where you do your actual work.
9090

91+
A bare repository is designed to be a shared hub — it accepts pushes
92+
from other repositories. You cannot run `git add` or `git commit`
93+
inside it because there is no working tree to stage files from. All
94+
changes must arrive via `git push` from another repository.
95+
96+
Pushing to a non-bare repository is rejected by default. The reason:
97+
a push updates the branch reference, but it does not touch the working
98+
tree. If Git allowed it, the person working in that repository would
99+
have files from the old commit while the branch points to the new one —
100+
their working tree and their branch would be out of sync, and any
101+
staged work could be silently lost. Bare repositories avoid this
102+
problem entirely because there is no working tree to desynchronize.
103+
91104
## 3. Object Model
92105

93106
Every time you commit, Git takes a **snapshot** — a complete picture of

0 commit comments

Comments
 (0)