[ostree] doc/repo: Describe object types

[Colin Walters <walters src gnome org>]

commit 7751d3d9cd7026b4dbd252631448ccc4ac58d2da
Author: Colin Walters <walters verbum org>
Date:   Fri Aug 23 17:21:31 2013 -0400

    doc/repo: Describe object types

 doc/repo.xml |   69 ++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 files changed, 55 insertions(+), 14 deletions(-)
---
diff --git a/doc/repo.xml b/doc/repo.xml
index ee367b9..dd49c28 100644
--- a/doc/repo.xml
+++ b/doc/repo.xml
@@ -8,29 +8,70 @@
   <chapter id="repository-intro">
     <title>Core object types and data model</title>
     <para>
-      OSTree is deeply inspired by git.  It is worth taking some time
+      OSTree is deeply inspired by git; like git, OSTree is a
+      userspace versioning filesystem.  It is worth taking some time
       to familiarize yourself with <ulink
       url="http://git-scm.com/book/en/Git-Internals";>Git
-      Internals</ulink>, as this section will assume some knowledge of how
-      git works.
+      Internals</ulink>, as this section will assume some knowledge of
+      how git works.
     </para>
     
     <para>
-      Like git, OSTree is a userspace versioning filesystem.  Its
-      object types are similar to git; it has commit objects and
+      Its object types are similar to git; it has commit objects and
       content objects.  Git has "tree" objects, whereas OSTree splits
       them into "dirtree" and "dirmeta" objects.  But unlike git,
-      OSTree's checksums are SHA256.  Its content objects include uid,
-      gid, and extended attributes (but still no timestamps).
+      OSTree's checksums are SHA256.  And most crucially, its content
+      objects include uid, gid, and extended attributes (but still no
+      timestamps).
     </para>
     
-    <para>
-      Also like git, each commit in OSTree can have a parent.  It is
-      designed to store a history of your binary builds, just like git
-      stores a history of source control.  However, OSTree also makes
-      it easy to delete data, under the assumption that you can
-      regenerate it from source code.
-    </para>
+    <simplesect id="commits">
+      <title>Commit objects</title>
+      <para>
+       A commit object contains metadata such as a timestamp, a log
+       message, and most importantly, a reference to a
+       dirtree/dirmeta pair of checksums which describe the root
+       directory of the filesystem.
+      </para>
+      <para>
+       Also like git, each commit in OSTree can have a parent.  It is
+       designed to store a history of your binary builds, just like git
+       stores a history of source control.  However, OSTree also makes
+       it easy to delete data, under the assumption that you can
+       regenerate it from source code.
+      </para>
+    </simplesect>
+
+    <simplesect id="dirtree">
+      <title>Dirtree objects</title>
+      <para>
+       A dirtree contains a sorted array of (filename, checksum)
+       pairs for content objects, and a second sorted array of
+       (filename, dirtree checksum, dirmeta checksum), which are
+       subdirectories.
+      </para>
+    </simplesect>
+
+    <simplesect id="dirmeta">
+      <title>Dirmeta objects</title>
+      <para>
+       In git, tree objects contain the metadata such as permissions
+       for their children.  But OSTree splits this into a separate
+       object to avoid duplicating extended attribute listings.
+      </para>
+    </simplesect>
+
+    <simplesect id="content">
+      <title>Content objects</title>
+      <para>
+       Unlike the first three object types which are metadata,
+       designed to be <literal>mmap()ed</literal>, the content object
+       has a separate internal header and payload sections.  The
+       header contains uid, gid, mode, and symbolic link target (for
+       symlinks), as well as extended attributes.  After the header,
+       for regular files, the content follows.
+      </para>
+    </simplesect>
   </chapter>
 
   <chapter id="repository-types">