Add 'nix registry' manpages

This also documents the registry format and matching/unification
semantics (though not quite correctly).
This commit is contained in:
Eelco Dolstra 2020-12-08 22:57:14 +01:00
parent 42cc98f8d6
commit e90e745232
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
6 changed files with 249 additions and 0 deletions

33
src/nix/registry-add.md Normal file
View file

@ -0,0 +1,33 @@
R""(
# Examples
* Set the `nixpkgs` flake identifier to a specific branch of Nixpkgs:
```console
# nix registry add nixpkgs github:NixOS/nixpkgs/nixos-20.03
```
* Pin `nixpkgs` to a specific revision:
```console
# nix registry add nixpkgs github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
```
* Add an entry that redirects a specific branch of `nixpkgs` to
another fork:
```console
# nix registry add nixpkgs/nixos-20.03 ~/Dev/nixpkgs
```
# Description
This command adds an entry to the user registry that maps flake
reference *from-url* to flake reference *to-url*. If an entry for
*from-url* already exists, it is overwritten.
Entries can be removed using [`nix registry
remove`](./nix3-registry-remove.md).
)""

29
src/nix/registry-list.md Normal file
View file

@ -0,0 +1,29 @@
R""(
# Examples
* Show the contents of all registries:
```console
# nix registry list
user flake:dwarffs github:edolstra/dwarffs/d181d714fd36eb06f4992a1997cd5601e26db8f5
system flake:nixpkgs path:/nix/store/fxl9mrm5xvzam0lxi9ygdmksskx4qq8s-source?lastModified=1605220118&narHash=sha256-Und10ixH1WuW0XHYMxxuHRohKYb45R%2fT8CwZuLd2D2Q=&rev=3090c65041104931adda7625d37fa874b2b5c124
global flake:blender-bin github:edolstra/nix-warez?dir=blender
global flake:dwarffs github:edolstra/dwarffs
```
# Description
This command displays the contents of all registries on standard
output. Each line represents one registry entry in the format *type*
*from* *to*, where *type* denotes the registry containing the entry:
* `flags`: entries specified on the command line using `--override-flake`.
* `user`: the user registry.
* `system`: the system registry.
* `global`: the global registry.
See the [`nix registry` manual page](./nix3-registry.md) for more details.
)""

38
src/nix/registry-pin.md Normal file
View file

@ -0,0 +1,38 @@
R""(
# Examples
* Pin `nixpkgs` to its most recent Git revision:
```console
# nix registry pin nixpkgs
```
Afterwards the user registry will have an entry like this:
```console
nix registry list | grep '^user '
user flake:nixpkgs github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
```
and `nix flake info` will say:
```console
# nix flake info nixpkgs
Resolved URL: github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
Locked URL: github:NixOS/nixpkgs/925b70cd964ceaedee26fde9b19cc4c4f081196a
```
# Description
This command adds an entry to the user registry that maps flake
reference *url* to the corresponding *locked* flake reference, that
is, a flake reference that specifies an exact revision or content
hash. This ensures that until this registry entry is removed, all uses
of *url* will resolve to exactly the same flake.
Entries can be removed using [`nix registry
remove`](./nix3-registry-remove.md).
)""

View file

@ -0,0 +1,16 @@
R""(
# Examples
* Remove the entry `nixpkgs` from the user registry:
```console
# nix registry remove nixpkgs
```
# Description
This command removes from the user registry any entry for flake
reference *url*.
)""

View file

@ -17,6 +17,13 @@ struct CmdRegistryList : StoreCommand
return "list available Nix flakes";
}
std::string doc() override
{
return
#include "registry-list.md"
;
}
void run(nix::ref<nix::Store> store) override
{
using namespace fetchers;
@ -47,6 +54,13 @@ struct CmdRegistryAdd : MixEvalArgs, Command
return "add/replace flake in user flake registry";
}
std::string doc() override
{
return
#include "registry-add.md"
;
}
CmdRegistryAdd()
{
expectArg("from-url", &fromUrl);
@ -75,6 +89,13 @@ struct CmdRegistryRemove : virtual Args, MixEvalArgs, Command
return "remove flake from user flake registry";
}
std::string doc() override
{
return
#include "registry-remove.md"
;
}
CmdRegistryRemove()
{
expectArg("url", &url);
@ -97,6 +118,13 @@ struct CmdRegistryPin : virtual Args, EvalCommand
return "pin a flake to its current version in user flake registry";
}
std::string doc() override
{
return
#include "registry-pin.md"
;
}
CmdRegistryPin()
{
expectArg("url", &url);
@ -132,6 +160,13 @@ struct CmdRegistry : virtual NixMultiCommand
return "manage the flake registry";
}
std::string doc() override
{
return
#include "registry.md"
;
}
Category category() override { return catSecondary; }
void run() override

98
src/nix/registry.md Normal file
View file

@ -0,0 +1,98 @@
R""(
# Description
`nix flake` provides subcommands for managing *flake
registries*. Flake registries are a convenience feature that allows
you to refer to flakes using symbolic identifiers such as `nixpkgs`,
rather than full URLs such as `git://github.com/NixOS/nixpkgs`. You
can use these identifiers on the command line (e.g. when you do `nix
run nixpkgs#hello`) or in flake input specifications in `flake.nix`
files. The latter are automatically resolved to full URLs and recorded
in the flake's `flake.lock` file.
In addition, the flake registry allows you to redirect arbitrary flake
references (e.g. `github:NixOS/patchelf`) to another location, such as
a local fork.
There are multiple registries. These are, in order from lowest to
highest precedence:
* The global registry, which is a file downloaded from the URL
specified by the setting `flake-registry`. It is cached locally and
updated automatically when it's older than `tarball-ttl`
seconds. The default global registry is kept in [a GitHub
repository](https://github.com/NixOS/flake-registry).
* The system registry, which is shared by all users. The default
location is `/etc/nix/registry.json`. On NixOS, the system registry
can be specified using the NixOS option `nix.registry`.
* The user registry `~/.config/nix/registry.json`. This registry can
be modified by commands such as `nix flake pin`.
* Overrides specified on the command line using the option
`--override-flake`.
# Registry format
A registry is a JSON file with the following format:
```json
{
"version": 2,
[
{
"from": {
"type": "indirect",
"id": "nixpkgs"
},
"to": {
"type": "github",
"owner": "NixOS",
"repo": "nixpkgs"
}
},
...
]
}
```
That is, it contains a list of objects with attributes `from` and
`to`, both of which contain a flake reference in attribute
representation. (For example, `{"type": "indirect", "id": "nixpkgs"}`
is the attribute representation of `nixpkgs`, while `{"type":
"github", "owner": "NixOS", "repo": "nixpkgs"}` is the attribute
representation of `github:NixOS/nixpkgs`.)
Given some flake reference *R*, a registry entry is used if its
`from` flake reference *matches* *R*. *R* is then replaced by the
*unification* of the `to` flake reference with *R*.
# Matching
The `from` flake reference in a registry entry *matches* some flake
reference *R* if the attributes in `from` are the same as the
attributes in `R`. For example:
* `nixpkgs` matches with `nixpkgs`.
* `nixpkgs` matches with `nixpkgs/nixos-20.09`.
* `nixpkgs/nixos-20.09` does not match with `nixpkgs`.
* `nixpkgs` does not match with `git://github.com/NixOS/patchelf`.
# Unification
The `to` flake reference in a registry entry is *unified* with some flake
reference *R* by taking `to` and applying the `rev` and `ref`
attributes from *R*, if specified. For example:
* `github:NixOS/nixpkgs` unified with `nixpkgs` produces `github:NixOS/nixpkgs`.
* `github:NixOS/nixpkgs` unified with `nixpkgs/nixos-20.09` produces `github:NixOS/nixpkgs/nixos-20.09`.
* `github:NixOS/nixpkgs/master` unified with `nixpkgs/nixos-20.09` produces `github:NixOS/nixpkgs/nixos-20.09`.
)""