wroclaw-git-backups/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2025-06-27 12:41:15 +02:00
Code Activity

Document file system object content addressing

Browse source 
In addition:

- Take the opportunity to add a bunch more missing hyperlinks, too.

- Remove some glossary entries that are now subsumed by dedicated pages.
  We used to not be able to do this without breaking link fragments, but
  now we can, so pick up where we left off.

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
This commit is contained in:
John Ericson 2024-04-09 17:07:39 -04:00
parent 87ab3c0ea4
commit 043135a848
33 changed files with 228 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/manual/src/command-ref/nix-collect-garbage.md
View file

@ -74,4 +74,4 @@ $ nix-collect-garbage -d
```
[profiles]: @docroot@/command-ref/files/profiles.md
[store objects]: @docroot@/glossary.md#gloss-store-object
[store objects]: @docroot@/store/store-object.md

2
doc/manual/src/command-ref/nix-env/delete-generations.md
View file

@ -49,7 +49,7 @@ Periodically deleting old generations is important to make garbage collection
effective.
The is because profiles are also garbage collection roots — any [store object] reachable from a profile is "alive" and ineligible for deletion.
[store object]: @docroot@/glossary.md#gloss-store-object
[store object]: @docroot@/store/store-object.md
{{#include ./opt-common.md}}

2
doc/manual/src/command-ref/nix-env/install.md
View file

@ -17,7 +17,7 @@
The install operation creates a new user environment.
It is based on the current generation of the active [profile](@docroot@/command-ref/files/profiles.md), to which a set of [store paths] described by *args* is added.
[store paths]: @docroot@/glossary.md#gloss-store-path
[store paths]: @docroot@/store/store-path.md
The arguments *args* map to store paths in a number of possible ways:

11
doc/manual/src/command-ref/nix-hash.md
View file

@ -20,16 +20,21 @@ an example.
The hash is computed over a *serialisation* of each path: a dump of
the file system tree rooted at the path. This allows directories and
symlinks to be hashed as well as regular files. The dump is in the
*NAR format* produced by [`nix-store
*[Nix Archive (NAR)][Nix Archive] format* produced by [`nix-store
--dump`](@docroot@/command-ref/nix-store/dump.md). Thus, `nix-hash path`
yields the same cryptographic hash as `nix-store --dump path |
md5sum`.
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
# Options
- `--flat`\
Print the cryptographic hash of the contents of each regular file
*path*. That is, do not compute the hash over the dump of *path*.
Print the cryptographic hash of the contents of each regular file *path*.
That is, instead of computing
the hash of the [Nix Archive (NAR)](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) of *path*,
just [directly hash]((@docroot@/store/file-system-object/content-address.md#serial-flat) *path* as is.
This requires *path* to resolve to a regular file rather than directory.
The result is identical to that produced by the GNU commands
`md5sum` and `sha1sum`.

6
doc/manual/src/command-ref/nix-store/dump.md
View file

@ -1,6 +1,6 @@
# Name
`nix-store --dump` - write a single path to a Nix Archive
`nix-store --dump` - write a single path to a [Nix Archive]
## Synopsis
@ -8,7 +8,7 @@
## Description
The operation `--dump` produces a NAR (Nix ARchive) file containing the
The operation `--dump` produces a [NAR (Nix ARchive)][Nix Archive] file containing the
contents of the file system tree rooted at *path*. The archive is
written to standard output.
@ -33,6 +33,8 @@ but not other types of files (such as device nodes).
A Nix archive can be unpacked using `nix-store
--restore`.
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
{{#include ./opt-common.md}}
{{#include ../opt-common.md}}

6
doc/manual/src/command-ref/nix-store/export.md
View file

@ -1,6 +1,6 @@
# Name
`nix-store --export` - export store paths to a Nix Archive
`nix-store --export` - export store paths to a [Nix Archive]
## Synopsis
@ -11,7 +11,7 @@
The operation `--export` writes a serialisation of the specified store
paths to standard output in a format that can be imported into another
Nix store with `nix-store --import`. This is like `nix-store
--dump`, except that the NAR archive produced by that command doesn’t
--dump`, except that the [Nix Archive (NAR)][Nix Archive] produced by that command doesn’t
contain the necessary meta-information to allow it to be imported into
another Nix store (namely, the set of references of the path).
@ -19,6 +19,8 @@ This command does not produce a *closure* of the specified paths, so if
a store path references other store paths that are missing in the target
Nix store, the import will fail.
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
{{#include ./opt-common.md}}
{{#include ../opt-common.md}}

4
doc/manual/src/command-ref/nix-store/import.md
View file

@ -1,6 +1,8 @@
# Name
`nix-store --import` - import Nix Archive into the store
`nix-store --import` - import [Nix Archive] into the store
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
# Synopsis

3
doc/manual/src/command-ref/nix-store/optimise.md
View file

@ -12,7 +12,7 @@ The operation `--optimise` reduces Nix store disk space usage by finding
identical files in the store and hard-linking them to each other. It
typically reduces the size of the store by something like 25-35%. Only
regular files and symlinks are hard-linked in this manner. Files are
considered identical when they have the same NAR archive serialisation:
considered identical when they have the same [Nix Archive (NAR)][Nix Archive] serialisation:
that is, regular files must have the same contents and permission
(executable or non-executable), and symlinks must have the same
contents.
@ -38,3 +38,4 @@ hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1'
there are 114486 files with equal contents out of 215894 files in total
```
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive

4
doc/manual/src/command-ref/nix-store/realise.md
View file

@ -25,11 +25,11 @@ Each of *paths* is processed as follows:
If no substitutes are available and no store derivation is given, realisation fails.
[store paths]: @docroot@/glossary.md#gloss-store-path
[store paths]: @docroot@/store/store-path.md
[valid]: @docroot@/glossary.md#gloss-validity
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
[output paths]: @docroot@/glossary.md#gloss-output-path
[store objects]: @docroot@/glossary.md#gloss-store-object
[store objects]: @docroot@/store/store-object.md
[closure]: @docroot@/glossary.md#gloss-closure
[substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
[content-addressed derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations

4
doc/manual/src/command-ref/nix-store/restore.md
View file

@ -8,9 +8,11 @@
## Description
The operation `--restore` unpacks a NAR archive to *path*, which must
The operation `--restore` unpacks a [Nix Archive (NAR)][Nix Archive] to *path*, which must
not already exist. The archive is read from standard input.
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
{{#include ./opt-common.md}}
{{#include ../opt-common.md}}