Skip to content

Commit 00e49ca

Browse files
brabojclaude
andcommitted
docs: simplify bare repo explanation for undergrad clarity
Replace push/pull/commit with sends/downloads/snapshots to avoid forward references. Soften "target branch checked out" to "where someone is actively working". Add transition question before the solution diagram. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 74cb19a commit 00e49ca

1 file changed

Lines changed: 18 additions & 17 deletions

File tree

chapters/02-building-blocks.md

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -100,8 +100,8 @@ $ git init --bare <directory-name>
100100

101101
Imagine two developers — Alice and Bob — working on the same project
102102
over a local network. Each has a non-bare repository with a working
103-
tree. There is no central server — Bob has Alice's repository set as
104-
his remote and sends changes directly into her `.git/` directory.
103+
tree. There is no central server — Bob sends his changes directly
104+
into Alice's `.git/` directory.
105105

106106
```text
107107
Alice (non-bare) Bob (non-bare)
@@ -110,26 +110,27 @@ his remote and sends changes directly into her `.git/` directory.
110110
│ files from A │ │ │
111111
│ + uncommitted │ │ │
112112
├──────────────────┤ ├──────────────────┤
113-
│ .git/ │ git push │ .git/ │
113+
│ .git/ │ sends │ .git/ │
114114
│ main → B ───────│◄─────────────│ main → B │
115115
│ (moved by push) │ │ │
116116
└──────────────────┘ └──────────────────┘
117117
⚠ OUT OF SYNC
118118
branch says B, files say A
119119
```
120120

121-
The problem: when Bob pushes his changes, Git updates the branch
122-
inside Alice's `.git/` to point to Bob's latest commit immediately. But Alice's
123-
working tree is **not** updated — her files still reflect the old commit, plus
124-
whatever edits she has in progress. Alice's branch and her working tree are
125-
now out of sync. If she commits at this point, she unknowingly **reverts Bob's
126-
changes** — because her files do not contain them. Git prevents this by
127-
refusing to accept a push to a non-bare repository that has the target
128-
branch checked out.
121+
The problem: when Bob sends his changes, Git updates the branch
122+
inside Alice's `.git/` to point to Bob's latest commit immediately.
123+
But Alice's working tree is **not** updated — her files still reflect
124+
the old commit, plus whatever edits she has in progress. Alice's
125+
branch and her working tree are now out of sync. If she records a
126+
snapshot at this point, she unknowingly **reverts Bob's changes**
127+
because her files do not contain them. Git prevents this by refusing
128+
to accept changes into a repository where someone is actively working.
129129

130-
A popular solution to this kind of synchronization problem is to decouple the
131-
direct push/pull between two developers and introduce an intermediary
132-
repository that both developers push to and pull from.
130+
What if the two developers never touch each other's repositories
131+
directly? A popular solution to this kind of synchronization problem
132+
is to introduce an intermediary repository that both developers send
133+
changes to and download changes from.
133134

134135
```text
135136
Alice (non-bare) Shared hub (bare) Bob (non-bare)
@@ -140,7 +141,7 @@ repository that both developers push to and pull from.
140141
│ .git/ │ │ │ │ .git/ │
141142
│ │◄───│ │◄───│ │
142143
└──────────────────┘ └──────────────────┘ └──────────────────┘
143-
pull push
144+
download send
144145
(when ready)
145146
```
146147

@@ -151,8 +152,8 @@ updating a branch is always safe.
151152

152153
With a bare repository in the middle, each developer works
153154
independently. Bob sends his changes to the bare repository whenever
154-
he is ready. Alice commits her own work first, then pulls Bob's
155-
changes from the bare repository when **she** is ready. No one
155+
he is ready. Alice records her own snapshots first, then downloads
156+
Bob's changes from the bare repository when **she** is ready. No one
156157
reaches into anyone else's working tree. This is exactly how
157158
hosting services like GitHub and GitLab work — every repository on
158159
the server is bare.

0 commit comments

Comments
 (0)