mirror of
https://github.com/ostreedev/ostree.git
synced 2024-10-26 17:25:36 +03:00
128 lines
4.9 KiB
XML
128 lines
4.9 KiB
XML
<?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; the core layer is a userspace
|
|
content-addressed 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.
|
|
</para>
|
|
|
|
<para>
|
|
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. And most crucially, its content
|
|
objects include uid, gid, and extended attributes (but still no
|
|
timestamps).
|
|
</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">
|
|
<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>
|