lib/core: introduce 'bare-split-xattrs' mode

docs/formats.md

@@ -63,18 +63,32 @@ Other disadvantages of `archive`:
  - One doesn't know the total size (compressed or uncompressed) of content
    before downloading everything
 
-## Aside: the bare and bare-user formats
+## Aside: bare formats
 
-The most common operation is to pull from an `archive` repository
-into a `bare` or `bare-user` formatted repository.  These latter two
-are not compressed on disk.  In other words, pulling to them is
-similar to unpacking (but not installing) an RPM/deb package.
+The most common operation is to pull from a remote `archive` repository
+into a local one.  This latter is not compressed on disk.  In other
+words, pulling to a local repository is similar to unpacking (but not
+installing) the content of an RPM/deb package.
+
+The `bare` repository format is the simplest one. In this mode regular files
+are directly stored to disk, and all metadata (e.g. uid/gid and xattrs) is
+reflected to the filesystem.
+It allows further direct access to content and metadata, but it may require
+elevated privileges when writing objects to the repository.
 
 The `bare-user` format is a bit special in that the uid/gid and xattrs
 from the content are ignored.  This is primarily useful if you want to
 have the same OSTree-managed content that can be run on a host system
 or an unprivileged container.
 
+Similarly, the `bare-split-xattrs` format is a special mode where xattrs
+are stored as separate repository objects, and not directly reflected to
+the filesystem.
+This is primarily useful when transporting xattrs through lossy environments
+(e.g. tar streams and containerized environments). It also allows carrying
+security-sensitive xattrs (e.g. SELinux labels) out-of-band without involving
+OS filesystem logic.
+
 ## Static deltas
 
 OSTree itself was originally focused on a continuous delivery model, where

docs/repo.md

@@ -81,15 +81,37 @@ warnings such as GNU Tar emitting "implausibly old time stamp" with 0; however,
 until we have a mechanism to transition cleanly to 1, for compatibilty OSTree
 is reverted to use zero again.
 
+### Xattrs objects
+
+In some repository modes (e.g. `bare-split-xattrs`), xattrs are stored on the
+side of the content objects they refer to. This is done via two dedicated
+object types, `file-xattrs` and `file-xattrs-link`.
+
+`file-xattrs` store xattrs data, encoded as GVariant. Each object is keyed by
+the checksum of the xattrs content, allowing for multiple references.
+
+`file-xattrs-link` are hardlinks which are associated to file objects.
+Each object is keyed by the same checksum of the corresponding file
+object. The target of the hardlink is an existing `file-xattrs` object.
+In case of reaching the limit of too many links, this object could be
+a plain file too.
+
 # Repository types and locations
 
-Also unlike git, an OSTree repository can be in one of four separate
-modes: `bare`, `bare-user`, `bare-user-only`, and `archive`.  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
+Also unlike git, an OSTree repository can be in one of five separate
+modes: `bare`, `bare-split-xattrs, ``bare-user`, `bare-user-only`, and
+`archive`.
+
+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.
 
+The `bare-split-xattrs` mode is similar to the above one, but it does store
+xattrs as separate objects.  This is meant to avoid conflicts with
+kernel-enforced constraints (e.g. on SELinux labels) and with other softwares
+that may perform ephemeral changes to xattrs (e.g. container runtimes).
+
 The `bare-user` mode is a later addition that is like `bare` in that
 files are unpacked, but it can (and should generally) be created as
 non-root.  In this mode, extended metadata such as owner uid, gid, and