From 7bf17f8825b7aacde8b4e3c5e035f6d442d649c4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 19 Jun 2023 05:45:08 +0200
Subject: [PATCH] Add description for file system objects (#8500)

While this is not actually a notion in the implementation, it is
explicitly described in the thesis and quite important for understanding
how the store works.

Co-authored-by: John Ericson <git@JohnEricson.me>
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
---
 doc/manual/src/SUMMARY.md.in                  |  3 +-
 .../src/architecture/file-system-object.md    | 64 +++++++++++++++++++
 doc/manual/src/glossary.md                    | 15 +++--
 3 files changed, 76 insertions(+), 6 deletions(-)
 create mode 100644 doc/manual/src/architecture/file-system-object.md

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index cfbb38be8..13d2e4d15 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -97,7 +97,8 @@
       - [manifest.json](command-ref/files/manifest.json.md)
     - [Channels](command-ref/files/channels.md)
     - [Default Nix expression](command-ref/files/default-nix-expression.md)
-- [Architecture](architecture/architecture.md)
+- [Architecture and Design](architecture/architecture.md)
+  - [File System Object](architecture/file-system-object.md)
 - [Protocols](protocols/protocols.md)
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
 - [Glossary](glossary.md)
diff --git a/doc/manual/src/architecture/file-system-object.md b/doc/manual/src/architecture/file-system-object.md
new file mode 100644
index 000000000..42f047260
--- /dev/null
+++ b/doc/manual/src/architecture/file-system-object.md
@@ -0,0 +1,64 @@
+# File System Object
+
+Nix uses a simplified model of the file system, which consists of file system objects.
+Every file system object is one of the following:
+
+ - File
+
+   - A possibly empty sequence of bytes for contents
+   - A single boolean representing the [executable](https://en.m.wikipedia.org/wiki/File-system_permissions#Permissions) permission
+
+ - Directory
+
+   Mapping of names to child file system objects
+
+ - [Symbolic link](https://en.m.wikipedia.org/wiki/Symbolic_link)
+
+   An arbitrary string.
+   Nix does not assign any semantics to symbolic links.
+
+File system objects and their children form a tree.
+A bare file or symlink can be a root file system object.
+
+Nix does not encode any other file system notions such as [hard links](https://en.m.wikipedia.org/wiki/Hard_link), [permissions](https://en.m.wikipedia.org/wiki/File-system_permissions), timestamps, or other metadata.
+
+## Examples of file system objects
+
+A plain file:
+
+```
+50 B, executable: false
+```
+
+An executable file:
+
+```
+122 KB, executable: true
+```
+
+A symlink:
+
+```
+-> /usr/bin/sh
+```
+
+A directory with contents:
+
+```
+├── bin
+│   └── hello: 35 KB, executable: true
+└── share
+    ├── info
+    │   └── hello.info: 36 KB, executable: false
+    └── man
+        └── man1
+            └── hello.1.gz: 790 B, executable: false
+```
+
+A directory that contains a symlink and other directories:
+
+```
+├── bin -> share/go/bin
+├── nix-support/
+└── share/
+```
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 47a484826..ac0bb3c2f 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -85,12 +85,17 @@
 
     [store path]: #gloss-store-path
 
+  - [file system object]{#gloss-store-object}\
+    The Nix data model for representing simplified file system data.
+
+    See [File System Object](@docroot@/architecture/file-system-object.md) for details.
+
+    [file system object]: #gloss-file-system-object
+
   - [store object]{#gloss-store-object}\
-    A file that is an immediate child of the Nix store directory. These
-    can be regular files, but also entire directory trees. Store objects
-    can be sources (objects copied from outside of the store),
-    derivation outputs (objects produced by running a build task), or
-    derivations (files describing a build task).
+
+    A store object consists of a [file system object], [reference]s to other store objects, and other metadata.
+    It can be referred to by a [store path].
 
     [store object]: #gloss-store-object