lix/doc/manual/src/command-ref/nix-channel.md

# Name

`nix-channel` - manage Nix channels

# Synopsis

`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--rollback` [*generation*] }

# 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.

To see the list of official NixOS channels, visit
<https://nixos.org/channels>.

This command has the following operations:

  - `--add` *url* \[*name*\]\
    Adds a channel named *name* with URL *url* to the list of subscribed
    channels. If *name* is omitted, it defaults to the last component of
    *url*, with the suffixes `-stable` or `-unstable` removed.

    A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
    At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.

  - `--remove` *name*\
    Removes the channel named *name* from the list of subscribed
    channels.

  - `--list`\
    Prints the names and URLs of all subscribed channels on standard
    output.

  - `--update` \[*names*…\]\
    Downloads the Nix expressions of all subscribed channels (or only
    those included in *names* if specified) and makes them the default
    for `nix-env` operations (by symlinking them from the directory
    `~/.nix-defexpr`).

  - `--rollback` \[*generation*\]\
    Reverts the previous call to `nix-channel
                    --update`. Optionally, you can specify a specific channel generation
    number to restore.

Note that `--add` does not automatically perform an update.

The list of subscribed channels is stored in `~/.nix-channels`.

{{#include ./opt-common.md}}

{{#include ./env-common.md}}

# Files

`nix-channel` operates on the following files.

{{#include ./files/channels.md}}

# Examples

To subscribe to the Nixpkgs channel and install the GNU Hello package:

```console
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update
$ nix-env --install --attr nixpkgs.hello
```

You can revert channel updates using `--rollback`:

```console
$ nix-instantiate --eval --expr '(import <nixpkgs> {}).lib.version'
"14.04.527.0e935f1"

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

$ nix-instantiate --eval --expr '(import <nixpkgs> {}).lib.version'
"14.04.526.dbadfad"
```
-												Clean up the manpages

											
										
										
											2020-07-24 10:56:19 +00:00
+								# Name
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
-												Clean up the manpages

											
										
										
											2020-07-24 10:56:19 +00:00
+								`nix-channel` - manage Nix channels
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
-												Clean up the manpages

											
										
										
											2020-07-24 10:56:19 +00:00
+								# Synopsis
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
-												Clean up the manpages

											
										
										
											2020-07-24 10:56:19 +00:00
+								`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--rollback` [*generation*] }
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
 								# 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.
 								To see the list of official NixOS channels, visit
 								<https://nixos.org/channels>.
 								This command has the following operations:
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 12:30:42 +00:00
+								  - `--add` *url* \[*name*\]\
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 12:28:05 +00:00
+								    Adds a channel named *name* with URL *url* to the list of subscribed
 								    channels. If *name* is omitted, it defaults to the last component of
 								    *url*, with the suffixes `-stable` or `-unstable` removed.
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
-												Document user files of nix

											
										
										
											2023-02-17 17:57:15 +00:00
+								    A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
 								    At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 12:30:42 +00:00
+								  - `--remove` *name*\
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 12:28:05 +00:00
+								    Removes the channel named *name* from the list of subscribed
 								    channels.
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 12:30:42 +00:00
+								  - `--list`\
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
+								    Prints the names and URLs of all subscribed channels on standard
 								    output.
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 12:30:42 +00:00
+								  - `--update` \[*names*…\]\
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
+								    Downloads the Nix expressions of all subscribed channels (or only
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 12:28:05 +00:00
+								    those included in *names* if specified) and makes them the default
 								    for `nix-env` operations (by symlinking them from the directory
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
+								    `~/.nix-defexpr`).
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 12:30:42 +00:00
+								  - `--rollback` \[*generation*\]\
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
+								    Reverts the previous call to `nix-channel
 								                    --update`. Optionally, you can specify a specific channel generation
 								    number to restore.
 								Note that `--add` does not automatically perform an update.
 								The list of subscribed channels is stored in `~/.nix-channels`.
-												Split nix-env and nix-store documentation per-subcommand

Documentation on "classic" commands with many sub-commands are
notoriously hard to discover due to lack of overview and anchor links.
Additionally the information on common options and environment variables
is not accessible offline in man pages, and therefore often overlooked
by readers.

With this change, each sub-command of nix-store and nix-env gets its
own page in the manual (listed in the table of contents), and each own
man page.

Also, man pages for each subcommand now (again) list common options
and environment variables. While this makes each page quite long and
some common parameters don't apply, this should still make it easier
to navigate as that additional information was not accessible on the
command line at all.

It is now possible to run 'nix-store --<subcommand> --help` to display
help pages for the given subcommand.

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

											
										
										
											2023-03-23 15:27:41 +00:00
+								{{#include ./opt-common.md}}
 								{{#include ./env-common.md}}
-												list files used by `nix-channel`

											
										
										
											2023-05-15 13:26:14 +00:00
+								# Files
 								`nix-channel` operates on the following files.
 								{{#include ./files/channels.md}}
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
+								# Examples
 								To subscribe to the Nixpkgs channel and install the GNU Hello package:
-												Enable syntax highlighting

											
										
										
											2020-07-31 13:43:25 +00:00
+								```console
 								$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
 								$ nix-channel --update
-												Convert short nix options to long ones

e.g. nix-env -e subversion => nix-env --uninstall subversion

The aim is to make the documentation less cryptic for newcomers and the
long options are more self-documenting.

The change was made with the following script:

<https://github.com/aschmolck/convert-short-nix-opts-to-long-ones>

and sanity checked visually.

											
										
										
											2023-04-30 13:52:38 +00:00
+								$ nix-env --install --attr nixpkgs.hello
-												Enable syntax highlighting

											
										
										
											2020-07-31 13:43:25 +00:00
+								```
-												Convert commands

											
										
										
											2020-07-23 10:58:42 +00:00
 								You can revert channel updates using `--rollback`:
-												Enable syntax highlighting

											
										
										
											2020-07-31 13:43:25 +00:00
+								```console
-												Convert short nix options to long ones

e.g. nix-env -e subversion => nix-env --uninstall subversion

The aim is to make the documentation less cryptic for newcomers and the
long options are more self-documenting.

The change was made with the following script:

<https://github.com/aschmolck/convert-short-nix-opts-to-long-ones>

and sanity checked visually.

											
										
										
											2023-04-30 13:52:38 +00:00
+								$ nix-instantiate --eval --expr '(import <nixpkgs> {}).lib.version'
-												Enable syntax highlighting

											
										
										
											2020-07-31 13:43:25 +00:00
+								"14.04.527.0e935f1"
-												Clean up the manpages

											
										
										
											2020-07-24 10:56:19 +00:00
-												Enable syntax highlighting

											
										
										
											2020-07-31 13:43:25 +00:00
+								$ nix-channel --rollback
 								switching from generation 483 to 482
-												Clean up the manpages

											
										
										
											2020-07-24 10:56:19 +00:00
-												Convert short nix options to long ones

e.g. nix-env -e subversion => nix-env --uninstall subversion

The aim is to make the documentation less cryptic for newcomers and the
long options are more self-documenting.

The change was made with the following script:

<https://github.com/aschmolck/convert-short-nix-opts-to-long-ones>

and sanity checked visually.

											
										
										
											2023-04-30 13:52:38 +00:00
+								$ nix-instantiate --eval --expr '(import <nixpkgs> {}).lib.version'
-												Enable syntax highlighting

											
										
										
											2020-07-31 13:43:25 +00:00
+								"14.04.526.dbadfad"
 								```