Skip to content

Commit

Permalink
reword documentation on nix-store --export (NixOS#10713)
Browse files Browse the repository at this point in the history
- add links to definitions of terms
- one sentence per line
- be more specific about which store is used for the import
- clearly distinguish store paths and store objects
- make a recommendation to use `nix-copy-closure` for efficient SSH transfers
  • Loading branch information
fricklerhandwerk authored May 20, 2024
1 parent e0bfa6c commit 209d755
Showing 1 changed file with 14 additions and 10 deletions.
24 changes: 14 additions & 10 deletions doc/manual/src/command-ref/nix-store/export.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,20 @@

## Description

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 [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).

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.
The operation `--export` writes a serialisation of the given [store objects](@docroot@/glossary.md#gloss-store-object) to standard output in a format that can be imported into another [Nix store](@docroot@/store/index.md) with [`nix-store --import`](./import.md).

> **Warning**
>
> This command *does not* produce a [closure](@docroot@/glossary.md#gloss-closure) of the specified store paths.
> Trying to import a store object that refers to store paths not available in the target Nix store will fail.
>
> Use [`nix-store --query`](@docroot@/command-ref/nix-store/query.md) to obtain the closure of a store path.
This command is different from [`nix-store --dump`](./dump.md), which produces a [Nix archive](@docroot@/glossary.md#gloss-nar) that *does not* contain the set of [references](@docroot@/glossary.md#gloss-reference) of a given store path.

> **Note**
>
> For efficient transfer of closures to remote machines over SSH, use [`nix-copy-closure`](@docroot@/command-ref/nix-copy-closure.md).
[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive

Expand Down

0 comments on commit 209d755

Please sign in to comment.