.\" -*- 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
\fCnix registry\fR - manage the flake registry
.SH
Synopsis
.LP
\fCnix registry\fR [\fIoption\fR\[u2026]] \fIsubcommand\fR
.PP
where \fIsubcommand\fR is one of the following:
.IP "\(bu" 3
\fB\fCnix registry add\fR\fR - add/replace flake in user flake registry
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\fCnix registry list\fR\fR - list available Nix flakes
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\fB\fCnix 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\fCnix registry remove\fR\fR - remove flake from user flake registry
.SH
Description
.LP
\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\(cqs \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" 3
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\(cqs older than \fCtarball-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 \fC/etc/nix/registry.json\fR. On NixOS, the system registry
can be specified using the NixOS option \fCnix.registry\fR.
.IP "\(bu" 3
The user registry \fC\(ti/.config/nix/registry.json\fR. This registry can
be modified by commands such as \fCnix registry pin\fR.
.IP "\(bu" 3
Overrides specified on the command line using the option
\fC--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 \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
.LP
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" 3
\fCnixpkgs\fR matches with \fCnixpkgs\fR.
.IP "\(bu" 3
\fCnixpkgs\fR matches with \fCnixpkgs/nixos-20.09\fR.
.IP "\(bu" 3
\fCnixpkgs/nixos-20.09\fR does not match with \fCnixpkgs\fR.
.IP "\(bu" 3
\fCnixpkgs\fR does not match with \fCgit://github.com/NixOS/patchelf\fR.
.SH
Unification
.LP
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" 3
\fCgithub:NixOS/nixpkgs\fR unified with \fCnixpkgs\fR produces \fCgithub:NixOS/nixpkgs\fR.
.IP "\(bu" 3
\fCgithub:NixOS/nixpkgs\fR unified with \fCnixpkgs/nixos-20.09\fR produces \fCgithub:NixOS/nixpkgs/nixos-20.09\fR.
.IP "\(bu" 3
\fCgithub:NixOS/nixpkgs/master\fR unified with \fCnixpkgs/nixos-20.09\fR produces \fCgithub:NixOS/nixpkgs/nixos-20.09\fR.
.SH
Options
.SS
Logging-related options
.IP "\(bu" 3
\fB\fC--debug\fR\fR
.IP
Set the logging verbosity level to \(oqdebug\(cq.
.IP "\(bu" 3
\fB\fC--log-format\fR\fR \fIformat\fR
.IP
Set the format of log output; one of \fCraw\fR, \fCinternal-json\fR, \fCbar\fR or \fCbar-with-logs\fR.
.IP "\(bu" 3
\fB\fC--print-build-logs\fR\fR / \fC-L\fR
.IP
Print full build logs on standard error.
.IP "\(bu" 3
\fB\fC--quiet\fR\fR
.IP
Decrease the logging verbosity level.
.IP "\(bu" 3
\fB\fC--verbose\fR\fR / \fC-v\fR
.IP
Increase the logging verbosity level.
.SS
Miscellaneous global options
.IP "\(bu" 3
\fB\fC--help\fR\fR
.IP
Show usage information.
.IP "\(bu" 3
\fB\fC--offline\fR\fR
.IP
Disable substituters and consider all previously downloaded files up-to-date.
.IP "\(bu" 3
\fB\fC--option\fR\fR \fIname\fR \fIvalue\fR
.IP
Set the Nix configuration setting \fIname\fR to \fIvalue\fR (overriding \fCnix.conf\fR).
.IP "\(bu" 3
\fB\fC--refresh\fR\fR
.IP
Consider all previously downloaded files out-of-date.
.IP "\(bu" 3
\fB\fC--version\fR\fR
.IP
Show version information.
.RS
.LP
\fBNote\fR
.PP
See \fB\fCman nix.conf\fR\fR for overriding configuration settings with command line flags.
.RE