forked from lix-project/lix
Add 'nix registry' manpages
This also documents the registry format and matching/unification semantics (though not quite correctly).
This commit is contained in:
parent
42cc98f8d6
commit
e90e745232
33
src/nix/registry-add.md
Normal file
33
src/nix/registry-add.md
Normal 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
29
src/nix/registry-list.md
Normal 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
38
src/nix/registry-pin.md
Normal 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).
|
||||
|
||||
)""
|
16
src/nix/registry-remove.md
Normal file
16
src/nix/registry-remove.md
Normal 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*.
|
||||
|
||||
)""
|
|
@ -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
98
src/nix/registry.md
Normal 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`.
|
||||
|
||||
)""
|
Loading…
Reference in a new issue