nix/doc/manual/command-ref/nix-channel.xml
Michael Fiano ad97d1a786
nix-channel grammar and punctuation
Minor changes to the nix-channel manpage for my first contribution
2018-03-01 00:27:25 -05:00

192 lines
6.4 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-channel">
<refmeta>
<refentrytitle>nix-channel</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">Nix</refmiscinfo>
<refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
</refmeta>
<refnamediv>
<refname>nix-channel</refname>
<refpurpose>manage Nix channels</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-channel</command>
<group choice='req'>
<arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></arg>
<arg choice='plain'><option>--remove</option> <replaceable>name</replaceable></arg>
<arg choice='plain'><option>--list</option></arg>
<arg choice='plain'><option>--update</option> <arg rep='repeat'><replaceable>names</replaceable></arg></arg>
<arg choice='plain'><option>--rollback</option> <arg choice='opt'><replaceable>generation</replaceable></arg></arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsection><title>Description</title>
<para>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 both a set of Nix
expressions and a pointer to a binary cache. <phrase
condition="manual">See also <xref linkend="sec-channels"
/>.</phrase></para>
<para>This command has the following operations:
<variablelist>
<varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term>
<listitem><para>Adds a channel named
<replaceable>name</replaceable> with URL
<replaceable>url</replaceable> to the list of subscribed channels.
If <replaceable>name</replaceable> is omitted, it defaults to the
last component of <replaceable>url</replaceable>, with the
suffixes <literal>-stable</literal> or
<literal>-unstable</literal> removed.</para></listitem>
</varlistentry>
<varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term>
<listitem><para>Removes the channel named
<replaceable>name</replaceable> from the list of subscribed
channels.</para></listitem>
</varlistentry>
<varlistentry><term><option>--list</option></term>
<listitem><para>Prints the names and URLs of all subscribed
channels on standard output.</para></listitem>
</varlistentry>
<varlistentry><term><option>--update</option> [<replaceable>names</replaceable>…]</term>
<listitem><para>Downloads the Nix expressions of all subscribed
channels (or only those included in
<replaceable>names</replaceable> if specified) and makes them the
default for <command>nix-env</command> operations (by symlinking
them from the directory
<filename>~/.nix-defexpr</filename>).</para></listitem>
</varlistentry>
<varlistentry><term><option>--rollback</option> [<replaceable>generation</replaceable>]</term>
<listitem><para>Reverts the previous call to <command>nix-channel
--update</command>. Optionally, you can specify a specific channel
generation number to restore.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>Note that <option>--add</option> does not automatically perform
an update.</para>
<para>The list of subscribed channels is stored in
<filename>~/.nix-channels</filename>.</para>
</refsection>
<refsection><title>Examples</title>
<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para>
<screen>
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update
$ nix-env -iA nixpkgs.hello</screen>
<para>You can revert channel updates using <option>--rollback</option>:</para>
<screen>
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
"14.04.527.0e935f1"
$ nix-channel --rollback
switching from generation 483 to 482
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
"14.04.526.dbadfad"
</screen>
</refsection>
<refsection><title>Files</title>
<variablelist>
<varlistentry><term><filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename></term>
<listitem><para><command>nix-channel</command> uses a
<command>nix-env</command> profile to keep track of previous
versions of the subscribed channels. Every time you run
<command>nix-channel --update</command>, a new channel generation
(that is, a symlink to the channel Nix expressions in the Nix store)
is created. This enables <command>nix-channel --rollback</command>
to revert to previous versions.</para></listitem>
</varlistentry>
<varlistentry><term><filename>~/.nix-defexpr/channels</filename></term>
<listitem><para>This is a symlink to
<filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename>. It
ensures that <command>nix-env</command> can find your channels. In
a multi-user installation, you may also have
<filename>~/.nix-defexpr/channels_root</filename>, which links to
the channels of the root user.</para></listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection><title>Channel format</title>
<para>A channel URL should point to a directory containing the
following files:</para>
<variablelist>
<varlistentry><term><filename>nixexprs.tar.xz</filename></term>
<listitem><para>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 <filename>default.nix</filename>
that serves as the channels “entry point”.</para></listitem>
</varlistentry>
<varlistentry><term><filename>binary-cache-url</filename></term>
<listitem><para>A file containing the URL to a binary cache (such
as <uri>https://cache.nixos.org</uri>). Nix will automatically
check this cache for pre-built binaries, if the user has
sufficient rights to add binary caches. For instance, in a
multi-user Nix setup, the binary caches provided by the channels
of the root user are used automatically, but caches corresponding
to the channels of non-root users are ignored.</para></listitem>
</varlistentry>
</variablelist>
</refsection>
</refentry>