diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index 41257e3de..95d0b03d4 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -278,7 +278,7 @@ $ nix-store --gc -Operation <option>--query</option> +Operation <option>--query</option> Synopsis @@ -674,7 +674,79 @@ in Nix itself. - + + +Operation <option>--dump</option> + + + Synopsis + + nix-store + + path + + + +Description + +The operation produces a NAR (Nix +ARchive) file containing the contents of the file system tree rooted +at path. The archive is written to +standard output. + +A NAR archive is like a TAR or Zip archive, but it contains only +the information that Nix considers important. For instance, +timestamps are elided because all files in the Nix store have their +timestamp set to 0 anyway. Likewise, all permissions are left out +except for the execute bit, because all files in the Nix store have +644 or 755 permission. + +Also, a NAR archive is canonical, meaning +that “equal” paths always produce the same NAR archive. For instance, +directory entries are always sorted so that the actual on-disk order +doesn’t influence the result. This means that the cryptographic hash +of a NAR dump of a path is usable as a fingerprint of the contents of +the path. Indeed, the hashes of store paths stored in Nix’s database +(see nix-store -q +--hash) are SHA-256 hashes of the NAR dump of each +store path. + +NAR archives support filenames of unlimited length and 64-bit +file sizes. They can contain regular files, directories, and symbolic +links, but not other types of files (such as device nodes). + +A Nix archive can be unpacked using nix-store +--restore. + + + + + + + + + +Operation <option>--restore</option> + + + Synopsis + + nix-store + + path + + + +Description + +The operation unpacks a NAR archive +to path, which must not already exist. The +archive is read from standard input. + + + + + diff --git a/src/nix-store/main.cc b/src/nix-store/main.cc index 42c3074ff..b83eb8837 100644 --- a/src/nix-store/main.cc +++ b/src/nix-store/main.cc @@ -599,7 +599,7 @@ struct StdinSource : RestoreSource }; -/* Restore a value from a Nix archive. The archive is written to +/* Restore a value from a Nix archive. The archive is read from standard input. */ static void opRestore(Strings opFlags, Strings opArgs) {