Skip to content

Commit 32fc31f

Browse files
brabojclaude
braboj
and
claude
committed
docs: polish chapter 2 — object model diagram, fix formatting
- Recreate object model diagram in palette C style (tag, commit, tree, blob as objects; branch, HEAD as references) - Fix legend: references stored in .git/HEAD and .git/refs/ - Add diagram before ASCII listing with explanatory prose - Fix missing blank line before Index heading - Archive old object-model and references PNGs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 497082f commit 32fc31f

5 files changed

Lines changed: 107 additions & 7 deletions

File tree

‎assets/archive/git-object-model.png‎

187 KB
Loading

assets/images/git-references.png renamed to assets/archive/git-references.png

File renamed without changes.

‎assets/drawio/git-object-model.drawio‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<mxfile host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/29.6.6 Chrome/144.0.7559.236 Electron/40.8.4 Safari/537.36">
2+
<diagram id="object-model" name="Object model">
3+
<mxGraphModel dx="625" dy="554" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="560" pageHeight="340" math="0" shadow="0">
4+
<root>
5+
<mxCell id="0" />
6+
<mxCell id="1" parent="0" />
7+
<mxCell id="bg-card" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#D3D1C7;strokeWidth=0.5;shadow=0;arcSize=5;" value="" vertex="1">
8+
<mxGeometry height="310" width="530" x="15" y="10" as="geometry" />
9+
</mxCell>
10+
<mxCell id="obj-tag" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#FEF9C3;strokeColor=#CA8A04;strokeWidth=0.5;shadow=0;fontSize=12;fontStyle=1;fontColor=#854D0E;fontFamily=Helvetica;verticalAlign=top;align=center;spacingTop=6;arcSize=10;" value="Tag" vertex="1">
11+
<mxGeometry height="55" width="90" x="40" y="40" as="geometry" />
12+
</mxCell>
13+
<mxCell id="tag-desc" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontSize=10;fontStyle=2;fontColor=#5F5E5A;fontFamily=Helvetica;" value="named label" vertex="1">
14+
<mxGeometry height="16" width="90" x="40" y="62" as="geometry" />
15+
</mxCell>
16+
<mxCell id="obj-commit" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F1F1F1;strokeColor=#888888;strokeWidth=0.5;shadow=0;fontSize=12;fontStyle=1;fontColor=#2C2C2A;fontFamily=Helvetica;verticalAlign=top;align=center;spacingTop=6;arcSize=10;" value="Commit" vertex="1">
17+
<mxGeometry height="55" width="90" x="220" y="40" as="geometry" />
18+
</mxCell>
19+
<mxCell id="commit-desc" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontSize=10;fontStyle=2;fontColor=#5F5E5A;fontFamily=Helvetica;" value="snapshot&amp;nbsp;&lt;div&gt;metadata&lt;/div&gt;" vertex="1">
20+
<mxGeometry height="38" width="110" x="210" y="62" as="geometry" />
21+
</mxCell>
22+
<mxCell id="obj-tree" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#FAECE7;strokeColor=#993C1D;strokeWidth=0.5;shadow=0;fontSize=12;fontStyle=1;fontColor=#712B13;fontFamily=Helvetica;verticalAlign=top;align=center;spacingTop=6;arcSize=10;" value="Tree" vertex="1">
23+
<mxGeometry height="55" width="90" x="220" y="160" as="geometry" />
24+
</mxCell>
25+
<mxCell id="tree-desc" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontSize=10;fontStyle=2;fontColor=#5F5E5A;fontFamily=Helvetica;" value="directory listing" vertex="1">
26+
<mxGeometry height="16" width="90" x="220" y="182" as="geometry" />
27+
</mxCell>
28+
<mxCell id="obj-blob" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F1EFE8;strokeColor=#5F5E5A;strokeWidth=0.5;shadow=0;fontSize=12;fontStyle=1;fontColor=#2C2C2A;fontFamily=Helvetica;verticalAlign=top;align=center;spacingTop=6;arcSize=10;" value="Blob" vertex="1">
29+
<mxGeometry height="35" width="90" x="220" y="270" as="geometry" />
30+
</mxCell>
31+
<mxCell id="ref-branch" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#DBEAFE;strokeColor=#2563EB;strokeWidth=0.5;arcSize=20;shadow=0;fontSize=12;fontStyle=1;fontColor=#1E40AF;fontFamily=Helvetica;verticalAlign=middle;align=center;" value="Branch" vertex="1">
32+
<mxGeometry height="30" width="90" x="390" y="52" as="geometry" />
33+
</mxCell>
34+
<mxCell id="ref-head" parent="1" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#DCFCE7;strokeColor=#16A34A;strokeWidth=0.5;arcSize=20;shadow=0;fontSize=12;fontStyle=1;fontColor=#15803D;fontFamily=Helvetica;verticalAlign=middle;align=center;" value="HEAD" vertex="1">
35+
<mxGeometry height="30" width="90" x="390" y="112" as="geometry" />
36+
</mxCell>
37+
<mxCell id="arr-tag-commit" edge="1" parent="1" source="obj-tag" style="endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;" target="obj-commit">
38+
<mxGeometry relative="1" as="geometry" />
39+
</mxCell>
40+
<mxCell id="label-parent" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=10;fontStyle=2;fontColor=#5F5E5A;fontFamily=Helvetica;" value="parent" vertex="1">
41+
<mxGeometry height="16" width="40" x="330" y="52" as="geometry" />
42+
</mxCell>
43+
<mxCell id="arr-commit-tree" edge="1" parent="1" source="obj-commit" style="endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;" target="obj-tree">
44+
<mxGeometry relative="1" as="geometry" />
45+
</mxCell>
46+
<mxCell id="arr-tree-blob" edge="1" parent="1" source="obj-tree" style="endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;" target="obj-blob">
47+
<mxGeometry relative="1" as="geometry" />
48+
</mxCell>
49+
<mxCell id="arr-tree-tree" edge="1" parent="1" source="obj-tree" style="endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;exitX=0;exitY=0.3;exitDx=0;exitDy=0;entryX=0;entryY=0.7;entryDx=0;entryDy=0;" target="obj-tree">
50+
<mxGeometry relative="1" as="geometry">
51+
<Array as="points">
52+
<mxPoint x="190" y="176" />
53+
<mxPoint x="190" y="199" />
54+
</Array>
55+
</mxGeometry>
56+
</mxCell>
57+
<mxCell id="label-subdir" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=right;verticalAlign=middle;fontSize=10;fontStyle=2;fontColor=#5F5E5A;fontFamily=Helvetica;" value="subdir" vertex="1">
58+
<mxGeometry height="16" width="38" x="150" y="180" as="geometry" />
59+
</mxCell>
60+
<mxCell id="arr-branch-commit" edge="1" parent="1" source="ref-branch" style="endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;dashed=1;dashPattern=4 3;edgeStyle=orthogonalEdgeStyle;" target="obj-commit">
61+
<mxGeometry relative="1" as="geometry" />
62+
</mxCell>
63+
<mxCell id="arr-head-branch" edge="1" parent="1" source="ref-head" style="endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;dashed=1;dashPattern=4 3;" target="ref-branch">
64+
<mxGeometry relative="1" as="geometry" />
65+
</mxCell>
66+
<mxCell id="leg-title" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;fontStyle=1;fontColor=#2C2C2A;fontFamily=Helvetica;" value="Objects" vertex="1">
67+
<mxGeometry height="18" width="60" x="20" y="220" as="geometry" />
68+
</mxCell>
69+
<mxCell id="leg-solid" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=10;fontStyle=2;fontColor=#5F5E5A;fontFamily=Helvetica;" value="── stored in .git/objects/" vertex="1">
70+
<mxGeometry height="16" width="160" x="20" y="238" as="geometry" />
71+
</mxCell>
72+
<mxCell id="leg-ref-title" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=11;fontStyle=1;fontColor=#2C2C2A;fontFamily=Helvetica;" value="References" vertex="1">
73+
<mxGeometry height="18" width="80" x="20" y="265" as="geometry" />
74+
</mxCell>
75+
<mxCell id="leg-dashed" parent="1" style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;fontSize=10;fontStyle=2;fontColor=#5F5E5A;fontFamily=Helvetica;" value="╌╌ stored in .git/HEAD and .git/refs/" vertex="1">
76+
<mxGeometry height="16" width="160" x="20" y="283" as="geometry" />
77+
</mxCell>
78+
<mxCell id="ExfScvuuNZ7uiJP0L8MA-2" edge="1" parent="1" source="obj-commit" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.714;entryY=0.006;entryDx=0;entryDy=0;entryPerimeter=0;exitX=0.25;exitY=0;exitDx=0;exitDy=0;curved=1;" target="obj-commit">
79+
<mxGeometry relative="1" as="geometry">
80+
<Array as="points">
81+
<mxPoint x="243" y="20" />
82+
<mxPoint x="284" y="20" />
83+
<mxPoint x="284" y="40" />
84+
<mxPoint x="284" y="40" />
85+
</Array>
86+
</mxGeometry>
87+
</mxCell>
88+
</root>
89+
</mxGraphModel>
90+
</diagram>
91+
</mxfile>

‎assets/images/git-object-model.png‎

-148 KB
Loading

‎chapters/02-building-blocks.md‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,17 @@ Tags are **not** pushed automatically — you must run
206206
207207
### How Objects Relate
208208

209+
The diagram below shows how objects and references connect. Objects
210+
(solid arrows) are immutable data stored in `.git/objects/`. References
211+
(dashed arrows) are named pointers stored in `.git/HEAD` and
212+
`.git/refs/` that give human-readable names to commits.
213+
214+
![Object Model](../assets/images/git-object-model.png)
215+
216+
Here is a concrete example showing two commits with their trees and
217+
blobs. Each commit is a full snapshot — commit N has four files,
218+
commit M has two:
219+
209220
```
210221
tag "v1.0"
211222
│
@@ -220,11 +231,8 @@ Tags are **not** pushed automatically — you must run
220231
└── blob .gitignore
221232
```
222233

223-
A **tag** points to a **commit**. Each commit points to its **parent**
224-
(the previous commit) and to a root **tree** (the project directory at
225-
that moment). The tree points to **blobs** (files) and other **trees**
226-
(subdirectories). Following these references from any commit, Git can
227-
reconstruct the exact state of every file at that point in time.
234+
Following these references from any commit, Git can reconstruct the
235+
exact state of every file at that point in time.
228236

229237
### How Objects Are Identified
230238

@@ -309,6 +317,7 @@ Add project documentation
309317
| `-t` | Object type | `commit`, `tree`, `blob`, or `tag` |
310318
| `-s` | Object size in bytes | `231` |
311319
| `-p` | Object content (pretty-print) | Depends on the type — see examples above |
320+
312321
## Index (Staging Area)
313322

314323
The index is the area between your working tree and the repository. It
@@ -486,8 +495,8 @@ move — you stay on your current branch.
486495

487496
```
488497
A ← B ← C (main, HEAD)
489-
↑ ↑
490-
fix feature
498+
↑ ↑
499+
fix feature
491500
```
492501

493502
A new branch can point to the current commit (`feature` at C) or to a

0 commit comments

Comments
 (0)