@@ -88,11 +88,64 @@ The `.git` folder contains the same structure as a bare repository.
8888The difference is that a non-bare repository also has a working tree
8989next to it — the place where you do your actual work.
9090
91- A bare repository is designed to be a shared hub. Because it has no
92- working tree, nobody edits files in it directly — it only receives
93- changes sent from other repositories. A non-bare repository is the
94- opposite: it is where you do your day-to-day work — editing files,
95- recording snapshots, and browsing history.
91+ ### Why bare repositories exist
92+
93+ Imagine two developers — Alice and Bob — working on the same project
94+ over a local network. Each has a non-bare repository with a working
95+ tree. There is no central server — Bob has Alice's repository set as
96+ his remote and sends changes directly into her ` .git/ ` directory.
97+
98+ ``` text
99+ Alice (non-bare) Bob (non-bare)
100+ ┌──────────────────┐ ┌──────────────────┐
101+ │ Working Tree │ │ Working Tree │
102+ │ files from A │ │ │
103+ │ + uncommitted │ │ │
104+ ├──────────────────┤ ├──────────────────┤
105+ │ .git/ │ git push │ .git/ │
106+ │ main → B ───────│◄────────────│ main → B │
107+ │ (moved by push) │ │ │
108+ └──────────────────┘ └──────────────────┘
109+ ⚠ OUT OF SYNC
110+ branch says B, files say A
111+ ```
112+
113+ The problem: when Bob sends his changes, Git updates the branch
114+ inside Alice's ` .git/ ` to point to Bob's latest commit. But Alice's
115+ working tree is ** not** updated — her files still reflect the old
116+ commit, plus whatever edits she has in progress. Alice's branch and
117+ her working tree are now out of sync. If she commits at this point,
118+ she unknowingly ** reverts Bob's changes** — because her files do not
119+ contain them.
120+
121+ Git prevents this by refusing to accept changes sent to a non-bare
122+ repository that has the target branch checked out.
123+
124+ The solution is to place a ** bare repository** between the two
125+ developers. A bare repository has no working tree — it holds only
126+ objects and references. Because nobody edits files in it, updating a
127+ branch is always safe.
128+
129+ ``` text
130+ Alice (non-bare) Shared hub (bare) Bob (non-bare)
131+ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
132+ │ Working Tree │ │ │ │ Working Tree │
133+ │ │ │ objects + refs │ │ │
134+ ├──────────────────┤ │ no working tree │ ├──────────────────┤
135+ │ .git/ │ │ │ │ .git/ │
136+ │ │◄───│ │◄───│ │
137+ └──────────────────┘ └──────────────────┘ └──────────────────┘
138+ pull push
139+ (when ready)
140+ ```
141+
142+ With a bare repository in the middle, each developer works
143+ independently. Bob sends his changes to the bare repository whenever
144+ he is ready. Alice commits her own work first, then downloads Bob's
145+ changes from the bare repository when ** she** is ready. No one
146+ reaches into anyone else's working tree. This is exactly how
147+ hosting services like GitHub and GitLab work — every repository on
148+ the server is bare.
96149
97150## 3. Object Model
98151
0 commit comments