puck/lix
0
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity
lix/doc/manual/src/command-ref/nix-channel.md

107 lines
3.4 KiB
Markdown
Raw Normal View History

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
Add nix-channel --list-generations Add support to --list-generations as another way to say nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations the way we did for nix-channel --rollback [generation id]
2021-05-13 17:33:03 +00:00
`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--list-generations` | `--rollback` [*generation*] }
Convert commands
2020-07-23 10:58:42 +00:00
# Description
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Channels are a mechanism for referencing remote Nix expressions and conveniently retrieving their latest version.
list moving parts of channels
2023-07-19 08:25:05 +00:00
The moving parts of channels are:
- The official channels listed at <https://nixos.org/channels>
- The user-specific list of [subscribed channels](#subscribed-channels)
- The [downloaded channel contents](#channels)
- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-i) or the [`NIX_PATH` environment variable](#env-NIX_PATH)
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
> **Note**
>
> The state of a subscribed channel is external to the Nix expressions relying on it.
> This may limit reproducibility.
>
> Dependencies on other Nix expressions can be declared explicitly with:
> - [`fetchurl`](@docroot@/language/builtins.md#builtins-fetchurl), [`fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball), or [`fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) in Nix expressions
> - the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I) in command line invocations
Convert commands
2020-07-23 10:58:42 +00:00
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*\]\
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Add a channel *name* located at *url* to the list of subscribed channels.
If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed.
> **Note**
>
> `--add` does not automatically perform an update.
> Use `--update` explicitly.
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*\
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Remove the channel *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`\
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Print the names and URLs of all subscribed channels on standard output.
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
- `--update` \[*names*…\]\
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Download the Nix expressions of subscribed channels and create a new generation.
Update all channels if none is specified, and only those included in *names* otherwise.
Convert commands
2020-07-23 10:58:42 +00:00
Add nix-channel --list-generations Add support to --list-generations as another way to say nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations the way we did for nix-channel --rollback [generation id]
2021-05-13 17:33:03 +00:00
- `--list-generations`\
Prints a list of all the current existing generations for the
channel profile.
Works the same way as
```
nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
```
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*\]\
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Revert channels to the state before the last call to `nix-channel --update`.
Optionally, you can specify a specific channel *generation* number to restore.
Convert commands
2020-07-23 10:58:42 +00:00
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
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Subscribe to the Nixpkgs channel and run `hello` from the GNU Hello package:
Convert commands
2020-07-23 10:58:42 +00:00
Enable syntax highlighting
2020-07-31 13:43:25 +00:00
```console
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
$ nix-channel --list
nixpkgs https://nixos.org/channels/nixpkgs
Enable syntax highlighting
2020-07-31 13:43:25 +00:00
$ nix-channel --update
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
$ nix-shell -p hello --run hello
hello
Enable syntax highlighting
2020-07-31 13:43:25 +00:00
```
Convert commands
2020-07-23 10:58:42 +00:00
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
Revert channel updates using `--rollback`:
Convert commands
2020-07-23 10:58:42 +00:00
Enable syntax highlighting
2020-07-31 13:43:25 +00:00
```console
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
$ nix-instantiate --eval '<nixpkgs>' --attr lib.version
"22.11pre296212.530a53dcbc9"
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
remove the Channels section this is a how-to guide which should not be in the reference manual. it also refers to `nix-env`, which should not be the first thing readers of the reference manual encounter, as it behaves very differently in spirit from the rest of Nix. slightly reword the documentation to be more concise and informative.
2023-03-05 02:59:17 +00:00
$ nix-instantiate --eval '<nixpkgs>' --attr lib.version
"22.11pre281526.d0419badfad"
```
Remove a channel:
```console
$ nix-channel --remove nixpkgs
$ nix-channel --list
Enable syntax highlighting
2020-07-31 13:43:25 +00:00
```
Copy permalink