max/nix-super
1
0
Fork 0
mirror of https://github.com/privatevoid-net/nix-super.git synced 2024-11-22 14:06:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

reword documentation on nix-copy-closure (#10709)

Browse source 
* reword documentation on `nix-copy-closure`

- one sentence per line
- be more precise with respect to which Nix stores are being accessed
- make a clear distinction between store paths and store objects
- add links to definitions of terms
- clarify which machine is which
- --to and --from don't take arguments

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
This commit is contained in:
Valentin Gagarin 2024-05-21 18:06:16 +02:00 committed by GitHub
parent b462a92b15
commit 77cb02b739
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 29 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
doc/manual/src/command-ref/nix-copy-closure.md
View file

@ -1,6 +1,6 @@
# Name # Name
`nix-copy-closure` - copy a closure to or from a remote machine via SSH `nix-copy-closure` - copy store objects to or from a remote machine via SSH
# Synopsis # Synopsis
@ -10,66 +10,55 @@
[`--include-outputs`] [`--include-outputs`]
[`--use-substitutes` | `-s`] [`--use-substitutes` | `-s`]
[`-v`] [`-v`]
_user@machine_ _paths_ [_user_@]_machine_[:_port_] _paths_
# Description # Description
`nix-copy-closure` gives you an easy and efficient way to exchange Given _paths_ from one machine, `nix-copy-closure` computes the [closure](@docroot@/glossary.md#gloss-closure) of those paths (i.e. all their dependencies in the Nix store), and copies [store objects](@docroot@/glossary.md#gloss-store-object) in that closure to another machine via SSH.
software between machines. Given one or more Nix store _paths_ on the It doesn’t copy store objects that are already present on the other machine.
local machine, `nix-copy-closure` computes the closure of those paths
(i.e. all their dependencies in the Nix store), and copies all paths
in the closure to the remote machine via the `ssh` (Secure Shell)
command. With the `--from` option, the direction is reversed: the
closure of _paths_ on a remote machine is copied to the Nix store on
the local machine.
This command is efficient because it only sends the store paths > **Note**
that are missing on the target machine. >
> While the Nix store to use on the local machine can be specified on the command line with the [`--store`](@docroot@/command-ref/conf-file.md#conf-store) option, the Nix store to be accessed on the remote machine can only be [configured statically](@docroot@/command-ref/conf-file.md#configuration-file) on that remote machine.
Since `nix-copy-closure` calls `ssh`, you may be asked to type in the Since `nix-copy-closure` calls `ssh`, you may need to authenticate with the remote machine.
appropriate password or passphrase. In fact, you may be asked _twice_ In fact, you may be asked for authentication _twice_ because `nix-copy-closure` currently connects twice to the remote machine: first to get the set of paths missing on the target machine, and second to send the dump of those paths.
because `nix-copy-closure` currently connects twice to the remote When using public key authentication, you can avoid typing the passphrase with `ssh-agent`.
machine, first to get the set of paths missing on the target machine,
and second to send the dump of those paths. When using public key
authentication, you can avoid typing the passphrase with `ssh-agent`.
# Options # Options
- `--to`\ - `--to`
Copy the closure of _paths_ from the local Nix store to the Nix
store on _machine_. This is the default.
- `--from`\ Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_.
Copy the closure of _paths_ from the Nix store on _machine_ to the This is the default behavior.
local Nix store.
- `--from`
Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified Nix store.
- `--gzip`
- `--gzip`\
Enable compression of the SSH connection. Enable compression of the SSH connection.
- `--include-outputs`\ - `--include-outputs`
Also copy the outputs of [store derivation]s included in the closure. Also copy the outputs of [store derivation]s included in the closure.
[store derivation]: @docroot@/glossary.md#gloss-store-derivation [store derivation]: @docroot@/glossary.md#gloss-store-derivation
- `--use-substitutes` / `-s`\ - `--use-substitutes` / `-s`
Attempt to download missing paths on the target machine using Nix’s
substitute mechanism. Any paths that cannot be substituted on the
target are still copied normally from the source. This is useful,
for instance, if the connection between the source and target
machine is slow, but the connection between the target machine and
`nixos.org` (the default binary cache server) is
fast.
- `-v`\ Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters).
Show verbose output. Any store objects that cannot be substituted on the target are still copied normally from the source.
This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}
# Environment variables # Environment variables
- `NIX_SSHOPTS`\ - `NIX_SSHOPTS`
Additional options to be passed to `ssh` on the command
line. Additional options to be passed to `ssh` on the command line.
{{#include ./env-common.md}} {{#include ./env-common.md}}