.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix3-registry" "1" ""
.PP
\fBWarning\fR: This program is \fBexperimental\fR and its interface is subject to change.
.SH Name
\fCnix registry\fR - manage the flake registry
.SH Synopsis
\fCnix registry\fR [\fIoption\fR\[u2026]] \fIsubcommand\fR
.PP
where \fIsubcommand\fR is one of the following:
.IP "\(bu" 2
\fB\fCnix registry add\fR\fR (\fI./nix3-registry-add.md\fR) - add/replace flake in user flake registry
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fB\fCnix registry list\fR\fR (\fI./nix3-registry-list.md\fR) - list available Nix flakes
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fB\fCnix registry pin\fR\fR (\fI./nix3-registry-pin.md\fR) - pin a flake to its current version or to the current version of a flake URL
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fB\fCnix registry remove\fR\fR (\fI./nix3-registry-remove.md\fR) - remove flake from user flake registry
.SH Description
\fCnix registry\fR provides subcommands for managing \fIflake
registries\fR. Flake registries are a convenience feature that allows
you to refer to flakes using symbolic identifiers such as \fCnixpkgs\fR,
rather than full URLs such as \fCgit://github.com/NixOS/nixpkgs\fR. You
can use these identifiers on the command line (e.g. when you do \fCnix
run nixpkgs#hello\fR) or in flake input specifications in \fCflake.nix\fR
files. The latter are automatically resolved to full URLs and recorded
in the flake\[u2019]s \fCflake.lock\fR file.
.PP
In addition, the flake registry allows you to redirect arbitrary flake
references (e.g. \fCgithub:NixOS/patchelf\fR) to another location, such as
a local fork.
.PP
There are multiple registries. These are, in order from lowest to
highest precedence:
.IP "\(bu" 2
The global registry, which is a file downloaded from the URL
specified by the setting \fCflake-registry\fR. It is cached locally and
updated automatically when it\[u2019]s older than \fCtarball-ttl\fR
seconds. The default global registry is kept in \fBa GitHub
repository\fR (\fIhttps://github.com/NixOS/flake-registry\fR).
.IP "\(bu" 2
The system registry, which is shared by all users. The default
location is \fC/etc/nix/registry.json\fR. On NixOS, the system registry
can be specified using the NixOS option \fCnix.registry\fR.
.IP "\(bu" 2
The user registry \fC\(ti/.config/nix/registry.json\fR. This registry can
be modified by commands such as \fCnix flake pin\fR.
.IP "\(bu" 2
Overrides specified on the command line using the option
\fC--override-flake\fR.
.SH Registry format
A registry is a JSON file with the following format:
.LP
.EX
{
  \(dqversion\(dq: 2,
  \(dqflakes\(dq: [
    {
      \(dqfrom\(dq: {
        \(dqtype\(dq: \(dqindirect\(dq,
        \(dqid\(dq: \(dqnixpkgs\(dq
      },
      \(dqto\(dq: {
        \(dqtype\(dq: \(dqgithub\(dq,
        \(dqowner\(dq: \(dqNixOS\(dq,
        \(dqrepo\(dq: \(dqnixpkgs\(dq
      }
    },
    ...
  ]
}
.EE
.PP
That is, it contains a list of objects with attributes \fCfrom\fR and
\fCto\fR, both of which contain a flake reference in attribute
representation. (For example, \fC{\(dqtype\(dq: \(dqindirect\(dq, \(dqid\(dq: \(dqnixpkgs\(dq}\fR
is the attribute representation of \fCnixpkgs\fR, while \fC{\(dqtype\(dq:
\(dqgithub\(dq, \(dqowner\(dq: \(dqNixOS\(dq, \(dqrepo\(dq: \(dqnixpkgs\(dq}\fR is the attribute
representation of \fCgithub:NixOS/nixpkgs\fR.)
.PP
Given some flake reference \fIR\fR, a registry entry is used if its
\fCfrom\fR flake reference \fImatches\fR \fIR\fR. \fIR\fR is then replaced by the
\fIunification\fR of the \fCto\fR flake reference with \fIR\fR.
.SH Matching
The \fCfrom\fR flake reference in a registry entry \fImatches\fR some flake
reference \fIR\fR if the attributes in \fCfrom\fR are the same as the
attributes in \fCR\fR. For example:
.IP "\(bu" 2
\fCnixpkgs\fR matches with \fCnixpkgs\fR.
.IP "\(bu" 2
\fCnixpkgs\fR matches with \fCnixpkgs/nixos-20.09\fR.
.IP "\(bu" 2
\fCnixpkgs/nixos-20.09\fR does not match with \fCnixpkgs\fR.
.IP "\(bu" 2
\fCnixpkgs\fR does not match with \fCgit://github.com/NixOS/patchelf\fR.
.SH Unification
The \fCto\fR flake reference in a registry entry is \fIunified\fR with some flake
reference \fIR\fR by taking \fCto\fR and applying the \fCrev\fR and \fCref\fR
attributes from \fIR\fR, if specified. For example:
.IP "\(bu" 2
\fCgithub:NixOS/nixpkgs\fR unified with \fCnixpkgs\fR produces \fCgithub:NixOS/nixpkgs\fR.
.IP "\(bu" 2
\fCgithub:NixOS/nixpkgs\fR unified with \fCnixpkgs/nixos-20.09\fR produces \fCgithub:NixOS/nixpkgs/nixos-20.09\fR.
.IP "\(bu" 2
\fCgithub:NixOS/nixpkgs/master\fR unified with \fCnixpkgs/nixos-20.09\fR produces \fCgithub:NixOS/nixpkgs/nixos-20.09\fR.