picnoir/Nix
1
0
Fork 0
Code Issues Pull requests 1 Releases Wiki Activity
Nix/doc/manual/src/command-ref/nix-env.md

91 lines
2.9 KiB
Markdown
Raw Normal View History

Clean up the manpages
2020-07-24 12:56:19 +02:00
# Name
Convert commands
2020-07-23 12:58:42 +02:00
Clean up the manpages
2020-07-24 12:56:19 +02:00
`nix-env` - manipulate or query Nix user environments
Convert commands
2020-07-23 12:58:42 +02:00
Clean up the manpages
2020-07-24 12:56:19 +02:00
# Synopsis
Convert commands
2020-07-23 12:58:42 +02: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 16:27:41 +01:00
`nix-env` *operation* [*options*] [*arguments…*]
Clean up the manpages
2020-07-24 12:56:19 +02:00
[`--option` *name* *value*]
[`--arg` *name* *value*]
[`--argstr` *name* *value*]
[{`--file` | `-f`} *path*]
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 16:27:41 +01:00
[{`--profile` | `-p`} *path*]
Clean up the manpages
2020-07-24 12:56:19 +02:00
[`--system-filter` *system*]
[`--dry-run`]
Convert commands
2020-07-23 12:58:42 +02:00
# Description
The command `nix-env` is used to manipulate Nix user environments. User
environments are sets of software packages available to a user at some
point in time. In other words, they are a synthesised view of the
programs available in the Nix store. There may be many user
environments: different users can have different environments, and
individual users can switch between different environments.
`nix-env` takes exactly one *operation* flag which indicates the
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 16:27:41 +01:00
subcommand to be performed. The following operations are available:
- [`--install`](./nix-env/install.md)
- [`--upgrade`](./nix-env/upgrade.md)
- [`--uninstall`](./nix-env/uninstall.md)
- [`--set`](./nix-env/set.md)
- [`--set-flag`](./nix-env/set-flag.md)
- [`--query`](./nix-env/query.md)
- [`--switch-profile`](./nix-env/switch-profile.md)
- [`--list-generations`](./nix-env/list-generations.md)
- [`--delete-generations`](./nix-env/delete-generations.md)
- [`--switch-generation`](./nix-env/switch-generation.md)
- [`--rollback`](./nix-env/rollback.md)
These pages can be viewed offline:
- `man nix-env-<operation>`.
Example: `man nix-env-install`
- `nix-env --help --<operation>`
Example: `nix-env --help --install`
Convert commands
2020-07-23 12:58:42 +02:00
# Selectors
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 15:52:38 +02:00
Several commands, such as `nix-env --query ` and `nix-env --install `, take a list of
Convert commands
2020-07-23 12:58:42 +02:00
arguments that specify the packages on which to operate. These are
extended regular expressions that must match the entire name of the
Fix logical and typographical errors in nix-env man page
2022-07-10 12:09:44 +02:00
package. (For details on regular expressions, see **regex**(7).) The match is
Convert commands
2020-07-23 12:58:42 +02:00
case-sensitive. The regular expression can optionally be followed by a
dash and a version number; if omitted, any version of the package will
match. Here are some examples:
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 14:30:42 +02:00
- `firefox`\
Convert commands
2020-07-23 12:58:42 +02:00
Matches the package name `firefox` and any version.
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 14:30:42 +02:00
- `firefox-32.0`\
Convert commands
2020-07-23 12:58:42 +02:00
Matches the package name `firefox` and version `32.0`.
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 14:30:42 +02:00
- `gtk\\+`\
Convert commands
2020-07-23 12:58:42 +02:00
Matches the package name `gtk+`. The `+` character must be escaped
using a backslash to prevent it from being interpreted as a
quantifier, and the backslash must be escaped in turn with another
backslash to ensure that the shell passes it on.
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 14:30:42 +02:00
- `.\*`\
Convert commands
2020-07-23 12:58:42 +02:00
Matches any package name. This is the default for most commands.
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 14:30:42 +02:00
- `'.*zip.*'`\
Convert commands
2020-07-23 12:58:42 +02:00
Matches any package name containing the string `zip`. Note the dots:
`'*zip*'` does not work, because in a regular expression, the
character `*` is interpreted as a quantifier.
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 14:30:42 +02:00
- `'.*(firefox|chromium).*'`\
Convert commands
2020-07-23 12:58:42 +02:00
Matches any package name containing the strings `firefox` or
`chromium`.
# Files
list files used by `nix-channel`
2023-05-15 15:26:14 +02:00
`nix-env` operates on the following files.
Document user files of nix
2023-02-17 18:57:15 +01:00
{{#include ./files/default-nix-expression.md}}
display documentation on manifest files separately it's probably better not to show the manifest file documentation in the command-specific pages, because these are implementation details that are not really practically useful. this means no additional hassle for building the manual, but clutters the table of contents a bit.
2023-04-27 11:56:52 +02:00
{{#include ./files/profiles.md}}
Reference in a new issue Copy permalink