From d6560deea3fe2cc6828fbf4024dc0bd0f1b111e0 Mon Sep 17 00:00:00 2001
From: Wolfgang Müller
Date: Mon, 17 May 2021 12:48:43 +0200
Subject: posts: Rewrite and improve 'Duly noted' section in signify-cgit.md

This commit attempts to clarify what exactly a tree is, and how trees
used for notes relate to "regular" trees. To that end, include real-life
examples and output from commands run in a repository that is publicly
accessible (in this case, quarg). This allows people who are interested
in the internals to follow along and poke around in the repository
themselves.

Many thanks to V for initial feedback and motivation for this change.
---
 posts/signify-cgit.md | 50 ++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 36 insertions(+), 14 deletions(-)

(limited to 'posts')

diff --git a/posts/signify-cgit.md b/posts/signify-cgit.md
index 7cbacba..ceea88c 100644
--- a/posts/signify-cgit.md
+++ b/posts/signify-cgit.md
@@ -27,24 +27,46 @@ Internally, Git stores the contents of a note as a
 saved to the object database and referred to by its hash. But Git must also
 store which commit a note belongs to. For this it uses a
 [tree](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#_tree_objects).
-Normally, a tree maps blobs (or other trees) to paths in the repository. The
-tree object that links notes, however, uses the commit blob as a "path". In the
-following tree printed by
-[`git-cat-file(1)`](https://git-scm.com/docs/git-cat-file), the note blobs are
-on the left side whilst the commit blobs are on the right:
+A tree is Git's way of encoding a directory: it contains a list of paths, and
+maps them to blobs (files) or other trees (subdirectories). We can look at those
+trees using [`git-cat-file(1)`](https://git-scm.com/docs/git-cat-file). For
+example, the following is the tree for [this
+commit](https://git.oriole.systems/quarg/commit/?id=7cd07362c4c13bfd01afa85a4666c491a020f330):
 
 ```
-100644 blob 6e3356af25efc1012279eb5e4c1bc5a31be16c31	22b910ba4985c6f1d91eaf9ac6c88e6fcb555115
-100644 blob c2daf0183bca1757216a792e9f770e8637db0d1b	36e553d961cc114c2f676108bdc28c7473a81fdc
-100644 blob bc82006e27fc0c79b282976703d97f78fbf4ebef	ebdc5a9bc9d5e303c08fb4a2126de02946b80d08
-100644 blob fc26da013cd8da9e95dd65433b9c8e423c20fbea	f5121f6db3a18421f857d84c1e85bbc7c45cbd24
+$ git cat-file -p 6a81213f2e88a33835f2fb94015bda5dc04a397c
+100644 blob 3feb78adc667d7bf4ad2cec4fb780b29ced25302	.gitignore
+100644 blob 2149bd82c51e65c34d8aee87f96c4f1c1af8f6c1	LICENSE
+100644 blob d397eaf5a75d0d30c4d9d2ffcd1007b44acc842a	quarg.1
+040000 tree eee3c892c769bad3b7d883f0a162500406f67c3b	quarg
+100644 blob 1a861ec51a39cbefa0f5027995c358af2224ebbb	setup.py
 ```
 
-The tree itself is then linked in a normal commit object that a special
-[ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) points
-to. By default, that is `refs/notes/commits`. One may think of that ref as
-pointing to a special branch holding all the information on notes "published" to
-that branch.
+The tree object that links notes, however, uses the commit blob itself as a
+"path". In the following tree (for
+[this](https://git.oriole.systems/quarg/commit/?h=refs/notes/signatures/tar.gz&id=f12709c0843a89b5be37fe499b9928a8c11cbcd9)
+commit) the note blob is on the left side whilst the commit blob ("path") is on
+the right:
+
+```
+$ git cat-file -p 3a5fd837cae7e478b9a230f6c301c93efda7c1e2
+100644 blob 5c7ec832f83342aa460bb27b0b75e12695a98a53	43c9fb13e063cebfd08e741b67b9ec2317aed4b9
+```
+
+Let's see which commit that is:
+
+```
+$ git show -s --pretty=oneline 43c9fb13e063cebfd08e741b67b9ec2317aed4b9
+43c9fb13e063cebfd08e741b67b9ec2317aed4b9 (tag: 0.1.2) Prepare for release of 0.1.2
+```
+
+The note tree is then linked in a normal [commit
+object](https://git.oriole.systems/quarg/commit/?h=refs/notes/signatures/tar.gz&id=f12709c0843a89b5be37fe499b9928a8c11cbcd9)
+that a special
+[ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) points to. By
+default, that is `refs/notes/commits`. One may think of that ref as pointing to
+a special branch holding all the information on notes "published" to that
+branch.
 
 Instead of that default location, cgit looks in `refs/notes/signatures/<format>`
 for any signatures. For example, signatures for a gzip-compressed tarball are
-- 
cgit v1.2.3-2-gb3c3