packaging
/
ostree
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Add repo docs

This commit is contained in:
Colin Walters 2013-08-21 08:26:24 -04:00
parent caf6be331b
commit 7e2e072ad4
3 changed files with 88 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Makefile.am
View File

@ -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

1
doc/ostree-docs.xml
View File

@ -12,6 +12,7 @@
</bookinfo>
<xi:include href="overview.xml"/>
<xi:include href="repo.xml"/>
<chapter xml:id="reference">
<title>API Reference</title>

86
doc/repo.xml Normal file
View File

@ -0,0 +1,86 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "../version.xml">
]>
<part id="repository">
<title>Anatomy of an OSTree repository</title>
<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
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.
</para>
<para>
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).
</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>
</chapter>
<chapter id="repository-types">
<title>Repository types and locations</title>
<para>
Also unlike git, an OSTree repository can be in one of two
separate modes: <literal>bare</literal> and
<literal>archive-z2</literal>. 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 <literal>archive-z2</literal> mode is designed
for serving via plain HTTP. Like tar files, it can be
read/written by non-root users.
</para>
<para>
On an OSTree-deployed system, the "system repository" is
<filename class='directory'>/ostree/repo</filename>. It can be
read by any uid, but only written by root. Unless the
<literal>--repo</literal> argument is given to the
<command>ostree</command> command, it will operate on the system
repository.
</para>
</chapter>
<chapter id="refs">
<title>Refs</title>
<para>
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
<literal>gnome-ostree/buildmaster/x86_64-runtime</literal> and
<literal>gnome-ostree/buildmaster/x86_64-devel-debug</literal>.
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.
</para>
<para>
The <command>ostree</command> supports a simple syntax using the
carat <literal>^</literal> to refer to the parent of a given
commit. For example,
<literal>gnome-ostree/buildmaster/x86_64-runtime^</literal>
refers to the previous build, and
<literal>gnome-ostree/buildmaster/x86_64-runtime^^</literal>
refers to the one before that.
</para>
</chapter>
</part>