doc: Add repo docs
This commit is contained in:
Colin Walters
parent
caf6be331b
commit
7e2e072ad4
|
|
@ -75,6 +75,7 @@ HTML_IMAGES=
|
||||||
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
|
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
|
||||||
content_files= \
|
content_files= \
|
||||||
overview.xml \
|
overview.xml \
|
||||||
|
repo.xml \
|
||||||
$(NULL)
|
$(NULL)
|
||||||
|
|
||||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||||
|
|
|
||||||
|
|
@ -12,6 +12,7 @@
|
||||||
</bookinfo>
|
</bookinfo>
|
||||||
|
|
||||||
<xi:include href="overview.xml"/>
|
<xi:include href="overview.xml"/>
|
||||||
|
<xi:include href="repo.xml"/>
|
||||||
|
|
||||||
<chapter xml:id="reference">
|
<chapter xml:id="reference">
|
||||||
<title>API Reference</title>
|
<title>API Reference</title>
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
Loading…
Reference in New Issue