diff --git a/doc/Makefile.am b/doc/Makefile.am
index b5acad6f..ef1e549c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -75,6 +75,7 @@ HTML_IMAGES=
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files= \
overview.xml \
+ repo.xml \
$(NULL)
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
diff --git a/doc/ostree-docs.xml b/doc/ostree-docs.xml
index 33936555..af3fd0c7 100644
--- a/doc/ostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -12,6 +12,7 @@
+
API Reference
diff --git a/doc/repo.xml b/doc/repo.xml
new file mode 100644
index 00000000..ee367b9e
--- /dev/null
+++ b/doc/repo.xml
@@ -0,0 +1,86 @@
+
+
+]>
+
+ Anatomy of an OSTree repository
+
+ Core object types and data model
+
+ OSTree is deeply inspired by git. It is worth taking some time
+ to familiarize yourself with Git
+ Internals, as this section will assume some knowledge of how
+ git works.
+
+
+
+ Like git, OSTree is a userspace versioning filesystem. 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).
+
+
+
+ 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.
+
+
+
+
+ Repository types and locations
+
+
+ Also unlike git, an OSTree repository can be in one of two
+ separate modes: bare and
+ archive-z2. A bare repository is one where
+ content files are just stored as regular files; it's designed to
+ be the source of a "hardlink farm", where each operating system
+ checkout is merely links into it. If you want to store files
+ owned by e.g. root in this mode, you must run OSTree as root.
+ In contrast, the archive-z2 mode is designed
+ for serving via plain HTTP. Like tar files, it can be
+ read/written by non-root users.
+
+
+
+ On an OSTree-deployed system, the "system repository" is
+ /ostree/repo. It can be
+ read by any uid, but only written by root. Unless the
+ --repo argument is given to the
+ ostree command, it will operate on the system
+ repository.
+
+
+
+
+ Refs
+
+ Like git, OSTree uses "refs" to which are text files that point
+ to particular commits (i.e. filesystem trees). For example, the
+ gnome-ostree operating system creates trees named like
+ gnome-ostree/buildmaster/x86_64-runtime and
+ gnome-ostree/buildmaster/x86_64-devel-debug.
+ These two refs point to two different generated filesystem
+ trees. In this example, the "runtime" tree contains just enough
+ to run a basic GNOME system, and "devel-debug" contains all of
+ the developer tools.
+
+
+
+ The ostree supports a simple syntax using the
+ carat ^ to refer to the parent of a given
+ commit. For example,
+ gnome-ostree/buildmaster/x86_64-runtime^
+ refers to the previous build, and
+ gnome-ostree/buildmaster/x86_64-runtime^^
+ refers to the one before that.
+
+
+