.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix-channel" "1" ""
.SH Name
\fCnix-channel\fR - manage Nix channels
.SH Synopsis
\fCnix-channel\fR {\fC--add\fR url [\fIname\fR] | \fC--remove\fR \fIname\fR | \fC--list\fR | \fC--update\fR [\fInames…\fR] | \fC--rollback\fR [\fIgeneration\fR] }
.SH Description
A Nix channel is a mechanism that allows you to automatically stay
up-to-date with a set of pre-built Nix expressions. A Nix channel is
just a URL that points to a place containing a set of Nix expressions.
.PP
To see the list of official NixOS channels, visit
\fIhttps://nixos.org/channels\fR.
.PP
This command has the following operations:
.IP "\(bu" 2
\fC--add\fR \fIurl\fR [\fIname\fR]
.br
Adds a channel named \fIname\fR with URL \fIurl\fR to the list of subscribed
channels. If \fIname\fR is omitted, it defaults to the last component of
\fIurl\fR, with the suffixes \fC-stable\fR or \fC-unstable\fR removed.
.IP "\(bu" 2
\fC--remove\fR \fIname\fR
.br
Removes the channel named \fIname\fR from the list of subscribed
channels.
.IP "\(bu" 2
\fC--list\fR
.br
Prints the names and URLs of all subscribed channels on standard
output.
.IP "\(bu" 2
\fC--update\fR [\fInames\fR…]
.br
Downloads the Nix expressions of all subscribed channels (or only
those included in \fInames\fR if specified) and makes them the default
for \fCnix-env\fR operations (by symlinking them from the directory
\fC\(ti/.nix-defexpr\fR).
.IP "\(bu" 2
\fC--rollback\fR [\fIgeneration\fR]
.br
Reverts the previous call to \fCnix-channel
--update\fR. Optionally, you can specify a specific channel generation
number to restore.
.LP
Note that \fC--add\fR does not automatically perform an update.
.PP
The list of subscribed channels is stored in \fC\(ti/.nix-channels\fR.
.SH Examples
To subscribe to the Nixpkgs channel and install the GNU Hello package:
.LP
.EX
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update
$ nix-env -iA nixpkgs.hello
.EE
.PP
You can revert channel updates using \fC--rollback\fR:
.LP
.EX
$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
\(dq14.04.527.0e935f1\(dq

$ nix-channel --rollback
switching from generation 483 to 482

$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
\(dq14.04.526.dbadfad\(dq
.EE
.SH Files
.IP "\(bu" 2
\fC/nix/var/nix/profiles/per-user/username/channels\fR
.br
\fCnix-channel\fR uses a \fCnix-env\fR profile to keep track of previous
versions of the subscribed channels. Every time you run \fCnix-channel
--update\fR, a new channel generation (that is, a symlink to the
channel Nix expressions in the Nix store) is created. This enables
\fCnix-channel --rollback\fR to revert to previous versions.
.IP "\(bu" 2
\fC\(ti/.nix-defexpr/channels\fR
.br
This is a symlink to
\fC/nix/var/nix/profiles/per-user/username/channels\fR. It ensures that
\fCnix-env\fR can find your channels. In a multi-user installation, you
may also have \fC\(ti/.nix-defexpr/channels_root\fR, which links to the
channels of the root user.
.SH Channel format
A channel URL should point to a directory containing the following
files:
.IP "\(bu" 2
\fCnixexprs.tar.xz\fR
.br
A tarball containing Nix expressions and files referenced by them
(such as build scripts and patches). At the top level, the tarball
should contain a single directory. That directory must contain a
file \fCdefault.nix\fR that serves as the channel’s “entry point”.