From 3744081c28d21962676c9adf1a8a8c82a14070c8 Mon Sep 17 00:00:00 2001 From: Jonathan Boulle Date: Fri, 16 Sep 2016 18:30:30 +0200 Subject: [PATCH 1/2] layer: clarify wording around applying changesets Signed-off-by: Jonathan Boulle --- layer.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/layer.md b/layer.md index fd7f48e68..9ed3b931b 100644 --- a/layer.md +++ b/layer.md @@ -204,31 +204,29 @@ The resulting tar archive for `rootfs-c9d-v1.s1` has the following entries: ./etc/.wh.my-app-config ``` -Where the basename name of `./etc/my-app-config` is now prefixed with `.wh.`, and will therefore be removed when the changeset is applied. +where the basename name of `./etc/my-app-config` is now prefixed with `.wh.`, and will therefore be removed when the changeset is applied. -## Applying +## Applying Changesets -Layer Changesets of [mediatype](./media-types.md) `application/vnd.oci.image.layer.v1.tar+gzip` are applied rather than strictly extracted in normal fashion for tar archives. +Layer Changesets of [mediatype](./media-types.md) `application/vnd.oci.image.layer.v1.tar+gzip` are _applied_, rather than simply extracted as tar archives. -Applying a layer changeset requires consideration for the [whiteout](#whiteouts) files. -In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive. +Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files. +In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive. ### Changeset over existing files -This section covers applying an entry in a layer changeset, if the file path already exists. +This section describes applying an entry from a layer changeset if the file path already exists. -If the file path is a directory, then the existing path just has it's attribute set from the layer changeset for that filepath. -If the file path is any other file type (regular file, FIFO, etc), then the: -* file path is unlinked (See [`unlink(2)`](http://linux.die.net/man/2/unlink)) -* create the file - * If a regular file then content written. -* set attributes on the filepath +If the entry and the existing path are both directories, then the existing path's attributes MUST be replaced by those of the entry in the changeset. +In all other cases, the implementation MUST do the semantic equivalent of the following: +- removing the file path (e.g. [`unlink(2)`](http://linux.die.net/man/2/unlink) on Linux systems) +- recreating the file path, based on the contents and attributes of the changeset entry ## Whiteouts A whiteout file is an empty file with a special filename that signifies a path should be deleted. -A whiteout filename consists of the prefix .wh. plus the basename of the path to be deleted. +A whiteout filename consists of the prefix `.wh.` plus the basename of the path to be deleted. As files prefixed with `.wh.` are special whiteout markers, it is not possible to create a filesystem which has a file or directory with a name beginning with `.wh.`. Once a whiteout is applied, the whiteout itself MUST also be hidden. From 6281e229196181f5f8d0c7bf6f0c19fd39ab8df8 Mon Sep 17 00:00:00 2001 From: Jonathan Boulle Date: Wed, 5 Oct 2016 14:20:06 +0200 Subject: [PATCH 2/2] layer: tweak wording Signed-off-by: Jonathan Boulle --- layer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/layer.md b/layer.md index 9ed3b931b..f28b03ee6 100644 --- a/layer.md +++ b/layer.md @@ -204,7 +204,7 @@ The resulting tar archive for `rootfs-c9d-v1.s1` has the following entries: ./etc/.wh.my-app-config ``` -where the basename name of `./etc/my-app-config` is now prefixed with `.wh.`, and will therefore be removed when the changeset is applied. +To signify that the resource `./etc/my-app-config` MUST be removed when the changeset is applied, the basename of the entry is prefixed with `.wh.`. ## Applying Changesets @@ -216,7 +216,7 @@ In the absence of any [whiteout](#whiteouts) files in a layer changeset, the arc ### Changeset over existing files -This section describes applying an entry from a layer changeset if the file path already exists. +This section specifies applying an entry from a layer changeset if the target path already exists. If the entry and the existing path are both directories, then the existing path's attributes MUST be replaced by those of the entry in the changeset. In all other cases, the implementation MUST do the semantic equivalent of the following: