.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix3-registry" "1" ""
.RS
.PP
\fBWarning\fR 
.br
This program is
\fB\fBexperimental\fR\fR
and its interface is subject to change.
.RE
.SH
Name
.LP
\f(CRnix registry\fR - manage the flake registry
.SH
Synopsis
.LP
\f(CRnix registry\fR [\fIoption\fR\[u2026]] \fIsubcommand\fR
.PP
where \fIsubcommand\fR is one of the following:
.IP "\(bu" 3
\fB\f(CRnix registry add\fR\fR - add/replace flake in user flake registry
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CRnix registry list\fR\fR - list available Nix flakes
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\f(CRnix registry pin\fR\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" 3
\fB\f(CRnix registry remove\fR\fR - remove flake from user flake registry
.SH
Description
.LP
\f(CRnix 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 \f(CRnixpkgs\fR,
rather than full URLs such as \f(CRgit://github.com/NixOS/nixpkgs\fR. You
can use these identifiers on the command line (e.g. when you do \f(CRnix
run nixpkgs#hello\fR) or in flake input specifications in \f(CRflake.nix\fR
files. The latter are automatically resolved to full URLs and recorded
in the flake\(cqs \f(CRflake.lock\fR file.
.PP
In addition, the flake registry allows you to redirect arbitrary flake
references (e.g. \f(CRgithub: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" 3
The global registry, which is a file downloaded from the URL
specified by the setting \f(CRflake-registry\fR. It is cached locally and
updated automatically when it\(cqs older than \f(CRtarball-ttl\fR
seconds. The default global registry is kept in \fBa GitHub
repository\fR.
.IP "\(bu" 3
The system registry, which is shared by all users. The default
location is \f(CR/etc/nix/registry.json\fR. On NixOS, the system registry
can be specified using the NixOS option \f(CRnix.registry\fR.
.IP "\(bu" 3
The user registry \f(CR\(ti/.config/nix/registry.json\fR. This registry can
be modified by commands such as \f(CRnix registry pin\fR.
.IP "\(bu" 3
Overrides specified on the command line using the option
\f(CR--override-flake\fR.
.SH
Registry format
.LP
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 \f(CRfrom\fR and
\f(CRto\fR, both of which contain a flake reference in attribute
representation. (For example, \f(CR{\(dqtype\(dq: \(dqindirect\(dq, \(dqid\(dq: \(dqnixpkgs\(dq}\fR
is the attribute representation of \f(CRnixpkgs\fR, while \f(CR{\(dqtype\(dq:
\(dqgithub\(dq, \(dqowner\(dq: \(dqNixOS\(dq, \(dqrepo\(dq: \(dqnixpkgs\(dq}\fR is the attribute
representation of \f(CRgithub:NixOS/nixpkgs\fR.)
.PP
Given some flake reference \fIR\fR, a registry entry is used if its
\f(CRfrom\fR flake reference \fImatches\fR \fIR\fR. \fIR\fR is then replaced by the
\fIunification\fR of the \f(CRto\fR flake reference with \fIR\fR.
.SH
Matching
.LP
The \f(CRfrom\fR flake reference in a registry entry \fImatches\fR some flake
reference \fIR\fR if the attributes in \f(CRfrom\fR are the same as the
attributes in \f(CRR\fR. For example:
.IP "\(bu" 3
\f(CRnixpkgs\fR matches with \f(CRnixpkgs\fR.
.IP "\(bu" 3
\f(CRnixpkgs\fR matches with \f(CRnixpkgs/nixos-20.09\fR.
.IP "\(bu" 3
\f(CRnixpkgs/nixos-20.09\fR does not match with \f(CRnixpkgs\fR.
.IP "\(bu" 3
\f(CRnixpkgs\fR does not match with \f(CRgit://github.com/NixOS/patchelf\fR.
.SH
Unification
.LP
The \f(CRto\fR flake reference in a registry entry is \fIunified\fR with some flake
reference \fIR\fR by taking \f(CRto\fR and applying the \f(CRrev\fR and \f(CRref\fR
attributes from \fIR\fR, if specified. For example:
.IP "\(bu" 3
\f(CRgithub:NixOS/nixpkgs\fR unified with \f(CRnixpkgs\fR produces \f(CRgithub:NixOS/nixpkgs\fR.
.IP "\(bu" 3
\f(CRgithub:NixOS/nixpkgs\fR unified with \f(CRnixpkgs/nixos-20.09\fR produces \f(CRgithub:NixOS/nixpkgs/nixos-20.09\fR.
.IP "\(bu" 3
\f(CRgithub:NixOS/nixpkgs/master\fR unified with \f(CRnixpkgs/nixos-20.09\fR produces \f(CRgithub:NixOS/nixpkgs/nixos-20.09\fR.