From 504b7abc452936b3118a18efea05026083ed8cdd Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Thu, 23 Jul 2020 12:58:42 +0200
Subject: Convert commands

---
 doc/manual/src/command-ref/nix-env.md | 926 ++++++++++++++++++++++++++++++++++
 1 file changed, 926 insertions(+)
 create mode 100644 doc/manual/src/command-ref/nix-env.md

(limited to 'doc/manual/src/command-ref/nix-env.md')

diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
new file mode 100644
index 000000000..90bf6ea08
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -0,0 +1,926 @@
+nix-env
+
+1
+
+Nix
+
+nix-env
+
+manipulate or query Nix user environments
+
+nix-env
+
+\--arg
+
+name
+
+value
+
+\--argstr
+
+name
+
+value
+
+\--file
+
+\-f
+
+path
+
+\--profile
+
+\-p
+
+path
+
+\--system-filter
+
+system
+
+\--dry-run
+
+operation
+
+options
+
+arguments
+
+# 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
+subcommand to be performed. These are documented below.
+
+# Selectors
+
+Several commands, such as `nix-env -q` and `nix-env -i`, take a list of
+arguments that specify the packages on which to operate. These are
+extended regular expressions that must match the entire name of the
+package. (For details on regular expressions, see regex7.) The match is
+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:
+
+  - `firefox`  
+    Matches the package name `firefox` and any version.
+
+  - `firefox-32.0`  
+    Matches the package name `firefox` and version `32.0`.
+
+  - `gtk\\+`  
+    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.
+
+  - `.\*`  
+    Matches any package name. This is the default for most commands.
+
+  - `'.*zip.*'`  
+    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.
+
+  - `'.*(firefox|chromium).*'`  
+    Matches any package name containing the strings `firefox` or
+    `chromium`.
+
+# Common options
+
+This section lists the options that are common to all operations. These
+options are allowed for every subcommand, though they may not always
+have an effect. See also [???](#sec-common-options).
+
+  - `--file` / `-f` path  
+    Specifies the Nix expression (designated below as the *active Nix
+    expression*) used by the `--install`, `--upgrade`, and `--query
+    --available` operations to obtain derivations. The default is
+    `~/.nix-defexpr`.
+    
+    If the argument starts with `http://` or `https://`, it is
+    interpreted as the URL of a tarball that will be downloaded and
+    unpacked to a temporary location. The tarball must include a single
+    top-level directory containing at least a file named `default.nix`.
+
+  - `--profile` / `-p` path  
+    Specifies the profile to be used by those operations that operate on
+    a profile (designated below as the *active profile*). A profile is a
+    sequence of user environments called *generations*, one of which is
+    the *current generation*.
+
+  - `--dry-run`  
+    For the `--install`, `--upgrade`, `--uninstall`,
+    `--switch-generation`, `--delete-generations` and `--rollback`
+    operations, this flag will cause `nix-env` to print what *would* be
+    done if this flag had not been specified, without actually doing it.
+    
+    `--dry-run` also prints out which paths will be
+    [substituted](#gloss-substitute) (i.e., downloaded) and which paths
+    will be built from source (because no substitute is available).
+
+  - `--system-filter` system  
+    By default, operations such as `--query
+                    --available` show derivations matching any platform. This option
+    allows you to use derivations for the specified platform system.
+
+<!-- end list -->
+
+# Files
+
+  - `~/.nix-defexpr`  
+    The source for the default Nix expressions used by the `--install`,
+    `--upgrade`, and `--query
+                    --available` operations to obtain derivations. The `--file` option
+    may be used to override this default.
+    
+    If `~/.nix-defexpr` is a file, it is loaded as a Nix expression. If
+    the expression is a set, it is used as the default Nix expression.
+    If the expression is a function, an empty set is passed as argument
+    and the return value is used as the default Nix expression.
+    
+    If `~/.nix-defexpr` is a directory containing a `default.nix` file,
+    that file is loaded as in the above paragraph.
+    
+    If `~/.nix-defexpr` is a directory without a `default.nix` file,
+    then its contents (both files and subdirectories) are loaded as Nix
+    expressions. The expressions are combined into a single set, each
+    expression under an attribute with the same name as the original
+    file or subdirectory.
+    
+    For example, if `~/.nix-defexpr` contains two files, `foo.nix` and
+    `bar.nix`, then the default Nix expression will essentially be
+    
+        {
+          foo = import ~/.nix-defexpr/foo.nix;
+          bar = import ~/.nix-defexpr/bar.nix;
+        }
+    
+    The file `manifest.nix` is always ignored. Subdirectories without a
+    `default.nix` file are traversed recursively in search of more Nix
+    expressions, but the names of these intermediate directories are not
+    added to the attribute paths of the default Nix expression.
+    
+    The command `nix-channel` places symlinks to the downloaded Nix
+    expressions from each subscribed channel in this directory.
+
+  - `~/.nix-profile`  
+    A symbolic link to the user's current profile. By default, this
+    symlink points to `prefix/var/nix/profiles/default`. The `PATH`
+    environment variable should include `~/.nix-profile/bin` for the
+    user environment to be visible to the user.
+
+# Operation `--install`
+
+## Synopsis
+
+nix-env
+
+\--install
+
+\-i
+
+\--preserve-installed
+
+\-P
+
+\--remove-all
+
+\-r
+
+args
+
+## Description
+
+The install operation creates a new user environment, based on the
+current generation of the active profile, to which a set of store paths
+described by args is added. The arguments args map to store paths in a
+number of possible ways:
+
+  - By default, args is a set of derivation names denoting derivations
+    in the active Nix expression. These are realised, and the resulting
+    output paths are installed. Currently installed derivations with a
+    name equal to the name of a derivation being added are removed
+    unless the option `--preserve-installed` is specified.
+    
+    If there are multiple derivations matching a name in args that have
+    the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
+    derivation with the highest *priority* is used. A derivation can
+    define a priority by declaring the `meta.priority` attribute. This
+    attribute should be a number, with a higher value denoting a lower
+    priority. The default priority is `0`.
+    
+    If there are multiple matching derivations with the same priority,
+    then the derivation with the highest version will be installed.
+    
+    You can force the installation of multiple derivations with the same
+    name by being specific about the versions. For instance, `nix-env -i
+    gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
+    probably cause a user environment conflict\!).
+
+  - If [`--attr`](#opt-attr) (`-A`) is specified, the arguments are
+    *attribute paths* that select attributes from the top-level Nix
+    expression. This is faster than using derivation names and
+    unambiguous. To find out the attribute paths of available packages,
+    use `nix-env -qaP`.
+
+  - If `--from-profile` path is given, args is a set of names denoting
+    installed store paths in the profile path. This is an easy way to
+    copy user environment elements from one profile to another.
+
+  - If `--from-expression` is given, args are Nix
+    [functions](#ss-functions) that are called with the active Nix
+    expression as their single argument. The derivations returned by
+    those function calls are installed. This allows derivations to be
+    specified in an unambiguous way, which is necessary if there are
+    multiple derivations with the same name.
+
+  - If args are store derivations, then these are
+    [realised](#rsec-nix-store-realise), and the resulting output paths
+    are installed.
+
+  - If args are store paths that are not store derivations, then these
+    are [realised](#rsec-nix-store-realise) and installed.
+
+  - By default all outputs are installed for each derivation. That can
+    be reduced by setting `meta.outputsToInstall`.
+
+## Flags
+
+  - `--prebuilt-only` / `-b`  
+    Use only derivations for which a substitute is registered, i.e.,
+    there is a pre-built binary available that can be downloaded in lieu
+    of building the derivation. Thus, no packages will be built from
+    source.
+
+  - `--preserve-installed`; `-P`  
+    Do not remove derivations with a name matching one of the
+    derivations being installed. Usually, trying to have two versions of
+    the same package installed in the same generation of a profile will
+    lead to an error in building the generation, due to file name
+    clashes between the two versions. However, this is not the case for
+    all packages.
+
+  - `--remove-all`; `-r`  
+    Remove all previously installed packages first. This is equivalent
+    to running `nix-env -e '.*'` first, except that everything happens
+    in a single transaction.
+
+## Examples
+
+To install a specific version of `gcc` from the active Nix expression:
+
+    $ nix-env --install gcc-3.3.2
+    installing `gcc-3.3.2'
+    uninstalling `gcc-3.1'
+
+Note the previously installed version is removed, since
+`--preserve-installed` was not specified.
+
+To install an arbitrary version:
+
+    $ nix-env --install gcc
+    installing `gcc-3.3.2'
+
+To install using a specific attribute:
+
+    $ nix-env -i -A gcc40mips
+    $ nix-env -i -A xorg.xorgserver
+
+To install all derivations in the Nix expression `foo.nix`:
+
+    $ nix-env -f ~/foo.nix -i '.*'
+
+To copy the store path with symbolic name `gcc` from another profile:
+
+    $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
+
+To install a specific store derivation (typically created by
+`nix-instantiate`):
+
+    $ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
+
+To install a specific output path:
+
+    $ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
+
+To install from a Nix expression specified on the command-line:
+
+    $ nix-env -f ./foo.nix -i -E \
+        'f: (f {system = "i686-linux";}).subversionWithJava'
+
+I.e., this evaluates to `(f: (f {system =
+"i686-linux";}).subversionWithJava) (import ./foo.nix)`, thus selecting
+the `subversionWithJava` attribute from the set returned by calling the
+function defined in `./foo.nix`.
+
+A dry-run tells you which paths will be downloaded or built from source:
+
+    $ nix-env -f '<nixpkgs>' -iA hello --dry-run
+    (dry run; not doing anything)
+    installing ‘hello-2.10’
+    this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
+      /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
+      ...
+
+To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12
+channel:
+
+    $ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
+
+# Operation `--upgrade`
+
+## Synopsis
+
+nix-env
+
+\--upgrade
+
+\-u
+
+\--lt
+
+\--leq
+
+\--eq
+
+\--always
+
+args
+
+## Description
+
+The upgrade operation creates a new user environment, based on the
+current generation of the active profile, in which all store paths are
+replaced for which there are newer versions in the set of paths
+described by args. Paths for which there are no newer versions are left
+untouched; this is not an error. It is also not an error if an element
+of args matches no installed derivations.
+
+For a description of how args is mapped to a set of store paths, see
+[`--install`](#rsec-nix-env-install). If args describes multiple store
+paths with the same symbolic name, only the one with the highest version
+is installed.
+
+## Flags
+
+  - `--lt`  
+    Only upgrade a derivation to newer versions. This is the default.
+
+  - `--leq`  
+    In addition to upgrading to newer versions, also “upgrade” to
+    derivations that have the same version. Version are not a unique
+    identification of a derivation, so there may be many derivations
+    that have the same version. This flag may be useful to force
+    “synchronisation” between the installed and available derivations.
+
+  - `--eq`  
+    *Only* “upgrade” to derivations that have the same version. This may
+    not seem very useful, but it actually is, e.g., when there is a new
+    release of Nixpkgs and you want to replace installed applications
+    with the same versions built against newer dependencies (to reduce
+    the number of dependencies floating around on your system).
+
+  - `--always`  
+    In addition to upgrading to newer versions, also “upgrade” to
+    derivations that have the same or a lower version. I.e., derivations
+    may actually be downgraded depending on what is available in the
+    active Nix expression.
+
+For the other flags, see `--install`.
+
+## Examples
+
+    $ nix-env --upgrade gcc
+    upgrading `gcc-3.3.1' to `gcc-3.4'
+    
+    $ nix-env -u gcc-3.3.2 --always (switch to a specific version)
+    upgrading `gcc-3.4' to `gcc-3.3.2'
+    
+    $ nix-env --upgrade pan
+    (no upgrades available, so nothing happens)
+    
+    $ nix-env -u (try to upgrade everything)
+    upgrading `hello-2.1.2' to `hello-2.1.3'
+    upgrading `mozilla-1.2' to `mozilla-1.4'
+
+## Versions
+
+The upgrade operation determines whether a derivation `y` is an upgrade
+of a derivation `x` by looking at their respective `name` attributes.
+The names (e.g., `gcc-3.3.1` are split into two parts: the package name
+(`gcc`), and the version (`3.3.1`). The version part starts after the
+first dash not followed by a letter. `x` is considered an upgrade of `y`
+if their package names match, and the version of `y` is higher that that
+of `x`.
+
+The versions are compared by splitting them into contiguous components
+of numbers and letters. E.g., `3.3.1pre5` is split into `[3, 3, 1,
+"pre", 5]`. These lists are then compared lexicographically (from left
+to right). Corresponding components `a` and `b` are compared as follows.
+If they are both numbers, integer comparison is used. If `a` is an empty
+string and `b` is a number, `a` is considered less than `b`. The special
+string component `pre` (for *pre-release*) is considered to be less than
+other components. String components are considered less than number
+components. Otherwise, they are compared lexicographically (i.e., using
+case-sensitive string comparison).
+
+This is illustrated by the following examples:
+
+    1.0 < 2.3
+    2.1 < 2.3
+    2.3 = 2.3
+    2.5 > 2.3
+    3.1 > 2.3
+    2.3.1 > 2.3
+    2.3.1 > 2.3a
+    2.3pre1 < 2.3
+    2.3pre3 < 2.3pre12
+    2.3a < 2.3c
+    2.3pre1 < 2.3c
+    2.3pre1 < 2.3q
+
+# Operation `--uninstall`
+
+## Synopsis
+
+nix-env
+
+\--uninstall
+
+\-e
+
+drvnames
+
+## Description
+
+The uninstall operation creates a new user environment, based on the
+current generation of the active profile, from which the store paths
+designated by the symbolic names names are removed.
+
+## Examples
+
+    $ nix-env --uninstall gcc
+    $ nix-env -e '.*' (remove everything)
+
+# Operation `--set`
+
+## Synopsis
+
+nix-env
+
+\--set
+
+drvname
+
+## Description
+
+The `--set` operation modifies the current generation of a profile so
+that it contains exactly the specified derivation, and nothing else.
+
+## Examples
+
+The following updates a profile such that its current generation will
+contain just Firefox:
+
+    $ nix-env -p /nix/var/nix/profiles/browser --set firefox
+
+# Operation `--set-flag`
+
+## Synopsis
+
+nix-env
+
+\--set-flag
+
+name
+
+value
+
+drvnames
+
+## Description
+
+The `--set-flag` operation allows meta attributes of installed packages
+to be modified. There are several attributes that can be usefully
+modified, because they affect the behaviour of `nix-env` or the user
+environment build script:
+
+  - `priority` can be changed to resolve filename clashes. The user
+    environment build script uses the `meta.priority` attribute of
+    derivations to resolve filename collisions between packages. Lower
+    priority values denote a higher priority. For instance, the GCC
+    wrapper package and the Binutils package in Nixpkgs both have a file
+    `bin/ld`, so previously if you tried to install both you would get a
+    collision. Now, on the other hand, the GCC wrapper declares a higher
+    priority than Binutils, so the former’s `bin/ld` is symlinked in the
+    user environment.
+
+  - `keep` can be set to `true` to prevent the package from being
+    upgraded or replaced. This is useful if you want to hang on to an
+    older version of a package.
+
+  - `active` can be set to `false` to “disable” the package. That is, no
+    symlinks will be generated to the files of the package, but it
+    remains part of the profile (so it won’t be garbage-collected). It
+    can be set back to `true` to re-enable the package.
+
+## Examples
+
+To prevent the currently installed Firefox from being upgraded:
+
+    $ nix-env --set-flag keep true firefox
+
+After this, `nix-env -u` will ignore Firefox.
+
+To disable the currently installed Firefox, then install a new Firefox
+while the old remains part of the profile:
+
+    $ nix-env -q
+    firefox-2.0.0.9 (the current one)
+    
+    $ nix-env --preserve-installed -i firefox-2.0.0.11
+    installing `firefox-2.0.0.11'
+    building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
+    collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
+      and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
+    (i.e., can’t have two active at the same time)
+    
+    $ nix-env --set-flag active false firefox
+    setting flag on `firefox-2.0.0.9'
+    
+    $ nix-env --preserve-installed -i firefox-2.0.0.11
+    installing `firefox-2.0.0.11'
+    
+    $ nix-env -q
+    firefox-2.0.0.11 (the enabled one)
+    firefox-2.0.0.9 (the disabled one)
+
+To make files from `binutils` take precedence over files from `gcc`:
+
+    $ nix-env --set-flag priority 5 binutils
+    $ nix-env --set-flag priority 10 gcc
+
+# Operation `--query`
+
+## Synopsis
+
+nix-env
+
+\--query
+
+\-q
+
+\--installed
+
+\--available
+
+\-a
+
+\--status
+
+\-s
+
+\--attr-path
+
+\-P
+
+\--no-name
+
+\--compare-versions
+
+\-c
+
+\--system
+
+\--drv-path
+
+\--out-path
+
+\--description
+
+\--meta
+
+\--xml
+
+\--json
+
+\--prebuilt-only
+
+\-b
+
+\--attr
+
+\-A
+
+attribute-path
+
+names
+
+## Description
+
+The query operation displays information about either the store paths
+that are installed in the current generation of the active profile
+(`--installed`), or the derivations that are available for installation
+in the active Nix expression (`--available`). It only prints information
+about derivations whose symbolic name matches one of names.
+
+The derivations are sorted by their `name` attributes.
+
+## Source selection
+
+The following flags specify the set of things on which the query
+operates.
+
+  - `--installed`  
+    The query operates on the store paths that are installed in the
+    current generation of the active profile. This is the default.
+
+  - `--available`; `-a`  
+    The query operates on the derivations that are available in the
+    active Nix expression.
+
+## Queries
+
+The following flags specify what information to display about the
+selected derivations. Multiple flags may be specified, in which case the
+information is shown in the order given here. Note that the name of the
+derivation is shown unless `--no-name` is specified.
+
+  - `--xml`  
+    Print the result in an XML representation suitable for automatic
+    processing by other tools. The root element is called `items`, which
+    contains a `item` element for each available or installed
+    derivation. The fields discussed below are all stored in attributes
+    of the `item` elements.
+
+  - `--json`  
+    Print the result in a JSON representation suitable for automatic
+    processing by other tools.
+
+  - `--prebuilt-only` / `-b`  
+    Show only derivations for which a substitute is registered, i.e.,
+    there is a pre-built binary available that can be downloaded in lieu
+    of building the derivation. Thus, this shows all packages that
+    probably can be installed quickly.
+
+  - `--status`; `-s`  
+    Print the *status* of the derivation. The status consists of three
+    characters. The first is `I` or `-`, indicating whether the
+    derivation is currently installed in the current generation of the
+    active profile. This is by definition the case for `--installed`,
+    but not for `--available`. The second is `P` or `-`, indicating
+    whether the derivation is present on the system. This indicates
+    whether installation of an available derivation will require the
+    derivation to be built. The third is `S` or `-`, indicating whether
+    a substitute is available for the derivation.
+
+  - `--attr-path`; `-P`  
+    Print the *attribute path* of the derivation, which can be used to
+    unambiguously select it using the [`--attr` option](#opt-attr)
+    available in commands that install derivations like `nix-env
+    --install`. This option only works together with `--available`
+
+  - `--no-name`  
+    Suppress printing of the `name` attribute of each derivation.
+
+  - `--compare-versions` / `-c`  
+    Compare installed versions to available versions, or vice versa (if
+    `--available` is given). This is useful for quickly seeing whether
+    upgrades for installed packages are available in a Nix expression. A
+    column is added with the following meaning:
+    
+      - `<` version  
+        A newer version of the package is available or installed.
+    
+      - `=` version  
+        At most the same version of the package is available or
+        installed.
+    
+      - `>` version  
+        Only older versions of the package are available or installed.
+    
+      - `- ?`  
+        No version of the package is available or installed.
+
+  - `--system`  
+    Print the `system` attribute of the derivation.
+
+  - `--drv-path`  
+    Print the path of the store derivation.
+
+  - `--out-path`  
+    Print the output path of the derivation.
+
+  - `--description`  
+    Print a short (one-line) description of the derivation, if
+    available. The description is taken from the `meta.description`
+    attribute of the derivation.
+
+  - `--meta`  
+    Print all of the meta-attributes of the derivation. This option is
+    only available with `--xml` or `--json`.
+
+## Examples
+
+To show installed packages:
+
+    $ nix-env -q
+    bison-1.875c
+    docbook-xml-4.2
+    firefox-1.0.4
+    MPlayer-1.0pre7
+    ORBit2-2.8.3
+    …
+
+To show available packages:
+
+    $ nix-env -qa
+    firefox-1.0.7
+    GConf-2.4.0.1
+    MPlayer-1.0pre7
+    ORBit2-2.8.3
+    …
+
+To show the status of available packages:
+
+    $ nix-env -qas
+    -P- firefox-1.0.7   (not installed but present)
+    --S GConf-2.4.0.1   (not present, but there is a substitute for fast installation)
+    --S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
+    IP- ORBit2-2.8.3    (installed and by definition present)
+    …
+
+To show available packages in the Nix expression `foo.nix`:
+
+    $ nix-env -f ./foo.nix -qa
+    foo-1.2.3
+
+To compare installed versions to what’s available:
+
+    $ nix-env -qc
+    ...
+    acrobat-reader-7.0 - ?      (package is not available at all)
+    autoconf-2.59      = 2.59   (same version)
+    firefox-1.0.4      < 1.0.7  (a more recent version is available)
+    ...
+
+To show all packages with “`zip`” in the name:
+
+    $ nix-env -qa '.*zip.*'
+    bzip2-1.0.6
+    gzip-1.6
+    zip-3.0
+    …
+
+To show all packages with “`firefox`” or “`chromium`” in the name:
+
+    $ nix-env -qa '.*(firefox|chromium).*'
+    chromium-37.0.2062.94
+    chromium-beta-38.0.2125.24
+    firefox-32.0.3
+    firefox-with-plugins-13.0.1
+    …
+
+To show all packages in the latest revision of the Nixpkgs repository:
+
+    $ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
+
+# Operation `--switch-profile`
+
+## Synopsis
+
+nix-env
+
+\--switch-profile
+
+\-S
+
+path
+
+## Description
+
+This operation makes path the current profile for the user. That is, the
+symlink `~/.nix-profile` is made to point to path.
+
+## Examples
+
+    $ nix-env -S ~/my-profile
+
+# Operation `--list-generations`
+
+## Synopsis
+
+nix-env
+
+\--list-generations
+
+## Description
+
+This operation print a list of all the currently existing generations
+for the active profile. These may be switched to using the
+`--switch-generation` operation. It also prints the creation date of the
+generation, and indicates the current generation.
+
+## Examples
+
+    $ nix-env --list-generations
+      95   2004-02-06 11:48:24
+      96   2004-02-06 11:49:01
+      97   2004-02-06 16:22:45
+      98   2004-02-06 16:24:33   (current)
+
+# Operation `--delete-generations`
+
+## Synopsis
+
+nix-env
+
+\--delete-generations
+
+generations
+
+## Description
+
+This operation deletes the specified generations of the current profile.
+The generations can be a list of generation numbers, the special value
+`old` to delete all non-current generations, a value such as `30d` to
+delete all generations older than the specified number of days (except
+for the generation that was active at that point in time), or a value
+such as `+5` to keep the last `5` generations ignoring any newer than
+current, e.g., if `30` is the current generation `+5` will delete
+generation `25` and all older generations. Periodically deleting old
+generations is important to make garbage collection effective.
+
+## Examples
+
+    $ nix-env --delete-generations 3 4 8
+    
+    $ nix-env --delete-generations +5
+    
+    $ nix-env --delete-generations 30d
+    
+    $ nix-env -p other_profile --delete-generations old
+
+# Operation `--switch-generation`
+
+## Synopsis
+
+nix-env
+
+\--switch-generation
+
+\-G
+
+generation
+
+## Description
+
+This operation makes generation number generation the current generation
+of the active profile. That is, if the `profile` is the path to the
+active profile, then the symlink `profile` is made to point to
+`profile-generation-link`, which is in turn a symlink to the actual user
+environment in the Nix store.
+
+Switching will fail if the specified generation does not exist.
+
+## Examples
+
+    $ nix-env -G 42
+    switching from generation 50 to 42
+
+# Operation `--rollback`
+
+## Synopsis
+
+nix-env
+
+\--rollback
+
+## Description
+
+This operation switches to the “previous” generation of the active
+profile, that is, the highest numbered generation lower than the current
+generation, if it exists. It is just a convenience wrapper around
+`--list-generations` and `--switch-generation`.
+
+## Examples
+
+    $ nix-env --rollback
+    switching from generation 92 to 91
+    
+    $ nix-env --rollback
+    error: no generation older than the current (91) exists
+
+# Environment variables
+
+  - `NIX_PROFILE`  
+    Location of the Nix profile. Defaults to the target of the symlink
+    `~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
+    otherwise.
-- 
cgit v1.2.3


From 802150f987e720452920a3d1993c3b4b36861116 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Thu, 23 Jul 2020 14:28:05 +0200
Subject: <replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.
---
 doc/manual/src/command-ref/nix-env.md | 61 ++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 30 deletions(-)

(limited to 'doc/manual/src/command-ref/nix-env.md')

diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index 90bf6ea08..90a2bd351 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -98,7 +98,7 @@ This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
 have an effect. See also [???](#sec-common-options).
 
-  - `--file` / `-f` path  
+  - `--file` / `-f` *path*  
     Specifies the Nix expression (designated below as the *active Nix
     expression*) used by the `--install`, `--upgrade`, and `--query
     --available` operations to obtain derivations. The default is
@@ -109,7 +109,7 @@ have an effect. See also [???](#sec-common-options).
     unpacked to a temporary location. The tarball must include a single
     top-level directory containing at least a file named `default.nix`.
 
-  - `--profile` / `-p` path  
+  - `--profile` / `-p` *path*  
     Specifies the profile to be used by those operations that operate on
     a profile (designated below as the *active profile*). A profile is a
     sequence of user environments called *generations*, one of which is
@@ -125,10 +125,10 @@ have an effect. See also [???](#sec-common-options).
     [substituted](#gloss-substitute) (i.e., downloaded) and which paths
     will be built from source (because no substitute is available).
 
-  - `--system-filter` system  
+  - `--system-filter` *system*  
     By default, operations such as `--query
                     --available` show derivations matching any platform. This option
-    allows you to use derivations for the specified platform system.
+    allows you to use derivations for the specified platform *system*.
 
 <!-- end list -->
 
@@ -200,17 +200,17 @@ args
 
 The install operation creates a new user environment, based on the
 current generation of the active profile, to which a set of store paths
-described by args is added. The arguments args map to store paths in a
-number of possible ways:
+described by *args* is added. The arguments *args* map to store paths in
+a number of possible ways:
 
-  - By default, args is a set of derivation names denoting derivations
+  - By default, *args* is a set of derivation names denoting derivations
     in the active Nix expression. These are realised, and the resulting
     output paths are installed. Currently installed derivations with a
     name equal to the name of a derivation being added are removed
     unless the option `--preserve-installed` is specified.
     
-    If there are multiple derivations matching a name in args that have
-    the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
+    If there are multiple derivations matching a name in *args* that
+    have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
     derivation with the highest *priority* is used. A derivation can
     define a priority by declaring the `meta.priority` attribute. This
     attribute should be a number, with a higher value denoting a lower
@@ -230,22 +230,23 @@ number of possible ways:
     unambiguous. To find out the attribute paths of available packages,
     use `nix-env -qaP`.
 
-  - If `--from-profile` path is given, args is a set of names denoting
-    installed store paths in the profile path. This is an easy way to
-    copy user environment elements from one profile to another.
+  - If `--from-profile` *path* is given, *args* is a set of names
+    denoting installed store paths in the profile *path*. This is an
+    easy way to copy user environment elements from one profile to
+    another.
 
-  - If `--from-expression` is given, args are Nix
+  - If `--from-expression` is given, *args* are Nix
     [functions](#ss-functions) that are called with the active Nix
     expression as their single argument. The derivations returned by
     those function calls are installed. This allows derivations to be
     specified in an unambiguous way, which is necessary if there are
     multiple derivations with the same name.
 
-  - If args are store derivations, then these are
+  - If *args* are store derivations, then these are
     [realised](#rsec-nix-store-realise), and the resulting output paths
     are installed.
 
-  - If args are store paths that are not store derivations, then these
+  - If *args* are store paths that are not store derivations, then these
     are [realised](#rsec-nix-store-realise) and installed.
 
   - By default all outputs are installed for each derivation. That can
@@ -359,12 +360,12 @@ args
 The upgrade operation creates a new user environment, based on the
 current generation of the active profile, in which all store paths are
 replaced for which there are newer versions in the set of paths
-described by args. Paths for which there are no newer versions are left
-untouched; this is not an error. It is also not an error if an element
-of args matches no installed derivations.
+described by *args*. Paths for which there are no newer versions are
+left untouched; this is not an error. It is also not an error if an
+element of *args* matches no installed derivations.
 
-For a description of how args is mapped to a set of store paths, see
-[`--install`](#rsec-nix-env-install). If args describes multiple store
+For a description of how *args* is mapped to a set of store paths, see
+[`--install`](#rsec-nix-env-install). If *args* describes multiple store
 paths with the same symbolic name, only the one with the highest version
 is installed.
 
@@ -462,7 +463,7 @@ drvnames
 
 The uninstall operation creates a new user environment, based on the
 current generation of the active profile, from which the store paths
-designated by the symbolic names names are removed.
+designated by the symbolic names *names* are removed.
 
 ## Examples
 
@@ -629,7 +630,7 @@ The query operation displays information about either the store paths
 that are installed in the current generation of the active profile
 (`--installed`), or the derivations that are available for installation
 in the active Nix expression (`--available`). It only prints information
-about derivations whose symbolic name matches one of names.
+about derivations whose symbolic name matches one of *names*.
 
 The derivations are sorted by their `name` attributes.
 
@@ -696,14 +697,14 @@ derivation is shown unless `--no-name` is specified.
     upgrades for installed packages are available in a Nix expression. A
     column is added with the following meaning:
     
-      - `<` version  
+      - `<` *version*  
         A newer version of the package is available or installed.
     
-      - `=` version  
+      - `=` *version*  
         At most the same version of the package is available or
         installed.
     
-      - `>` version  
+      - `>` *version*  
         Only older versions of the package are available or installed.
     
       - `- ?`  
@@ -806,8 +807,8 @@ path
 
 ## Description
 
-This operation makes path the current profile for the user. That is, the
-symlink `~/.nix-profile` is made to point to path.
+This operation makes *path* the current profile for the user. That is,
+the symlink `~/.nix-profile` is made to point to *path*.
 
 ## Examples
 
@@ -882,9 +883,9 @@ generation
 
 ## Description
 
-This operation makes generation number generation the current generation
-of the active profile. That is, if the `profile` is the path to the
-active profile, then the symlink `profile` is made to point to
+This operation makes generation number *generation* the current
+generation of the active profile. That is, if the `profile` is the path
+to the active profile, then the symlink `profile` is made to point to
 `profile-generation-link`, which is in turn a symlink to the actual user
 environment in the Nix store.
 
-- 
cgit v1.2.3


From 758c9ee1bb0e9d4bea420420af93e0128fabf188 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Fri, 24 Jul 2020 12:56:19 +0200
Subject: Clean up the manpages

---
 doc/manual/src/command-ref/nix-env.md | 284 ++++++++++------------------------
 1 file changed, 82 insertions(+), 202 deletions(-)

(limited to 'doc/manual/src/command-ref/nix-env.md')

diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index 90a2bd351..cf688100e 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -1,50 +1,20 @@
-nix-env
+Title: nix-env
 
-1
+# Name
 
-Nix
+`nix-env` - manipulate or query Nix user environments
 
-nix-env
+# Synopsis
 
-manipulate or query Nix user environments
-
-nix-env
-
-\--arg
-
-name
-
-value
-
-\--argstr
-
-name
-
-value
-
-\--file
-
-\-f
-
-path
-
-\--profile
-
-\-p
-
-path
-
-\--system-filter
-
-system
-
-\--dry-run
-
-operation
-
-options
-
-arguments
+`nix-env`
+  [`--option` *name* *value*]
+  [`--arg` *name* *value*]
+  [`--argstr` *name* *value*]
+  [{`--file` | `-f`} *path*]
+  [{`--profile` | `-p`} *path(]
+  [`--system-filter` *system*]
+  [`--dry-run`]
+  *operation* [*options…*] [*arguments…*]
 
 # Description
 
@@ -103,7 +73,7 @@ have an effect. See also [???](#sec-common-options).
     expression*) used by the `--install`, `--upgrade`, and `--query
     --available` operations to obtain derivations. The default is
     `~/.nix-defexpr`.
-    
+
     If the argument starts with `http://` or `https://`, it is
     interpreted as the URL of a tarball that will be downloaded and
     unpacked to a temporary location. The tarball must include a single
@@ -120,7 +90,7 @@ have an effect. See also [???](#sec-common-options).
     `--switch-generation`, `--delete-generations` and `--rollback`
     operations, this flag will cause `nix-env` to print what *would* be
     done if this flag had not been specified, without actually doing it.
-    
+
     `--dry-run` also prints out which paths will be
     [substituted](#gloss-substitute) (i.e., downloaded) and which paths
     will be built from source (because no substitute is available).
@@ -135,38 +105,38 @@ have an effect. See also [???](#sec-common-options).
 # Files
 
   - `~/.nix-defexpr`  
-    The source for the default Nix expressions used by the `--install`,
-    `--upgrade`, and `--query
-                    --available` operations to obtain derivations. The `--file` option
-    may be used to override this default.
-    
+    The source for the default Nix expressions used by the
+    `--install`, `--upgrade`, and `--query --available` operations to
+    obtain derivations. The `--file` option may be used to override
+    this default.
+
     If `~/.nix-defexpr` is a file, it is loaded as a Nix expression. If
     the expression is a set, it is used as the default Nix expression.
     If the expression is a function, an empty set is passed as argument
     and the return value is used as the default Nix expression.
-    
+
     If `~/.nix-defexpr` is a directory containing a `default.nix` file,
     that file is loaded as in the above paragraph.
-    
+
     If `~/.nix-defexpr` is a directory without a `default.nix` file,
     then its contents (both files and subdirectories) are loaded as Nix
     expressions. The expressions are combined into a single set, each
     expression under an attribute with the same name as the original
     file or subdirectory.
-    
+
     For example, if `~/.nix-defexpr` contains two files, `foo.nix` and
     `bar.nix`, then the default Nix expression will essentially be
-    
+
         {
           foo = import ~/.nix-defexpr/foo.nix;
           bar = import ~/.nix-defexpr/bar.nix;
         }
-    
+
     The file `manifest.nix` is always ignored. Subdirectories without a
     `default.nix` file are traversed recursively in search of more Nix
     expressions, but the names of these intermediate directories are not
     added to the attribute paths of the default Nix expression.
-    
+
     The command `nix-channel` places symlinks to the downloaded Nix
     expressions from each subscribed channel in this directory.
 
@@ -180,21 +150,13 @@ have an effect. See also [???](#sec-common-options).
 
 ## Synopsis
 
-nix-env
-
-\--install
-
-\-i
-
-\--preserve-installed
-
-\-P
-
-\--remove-all
-
-\-r
-
-args
+`nix-env` {`--install` | `-i`} *args…*
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`}]
+  [`--from-expression`] [`-E`]
+  [`--from-profile` *path*]
+  [`--preserve-installed` | `-P`]
+  [`--remove-all` | `-r`]
 
 ## Description
 
@@ -208,17 +170,17 @@ a number of possible ways:
     output paths are installed. Currently installed derivations with a
     name equal to the name of a derivation being added are removed
     unless the option `--preserve-installed` is specified.
-    
+
     If there are multiple derivations matching a name in *args* that
     have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
     derivation with the highest *priority* is used. A derivation can
     define a priority by declaring the `meta.priority` attribute. This
     attribute should be a number, with a higher value denoting a lower
     priority. The default priority is `0`.
-    
+
     If there are multiple matching derivations with the same priority,
     then the derivation with the highest version will be installed.
-    
+
     You can force the installation of multiple derivations with the same
     name by being specific about the versions. For instance, `nix-env -i
     gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
@@ -339,21 +301,13 @@ channel:
 
 ## Synopsis
 
-nix-env
-
-\--upgrade
-
-\-u
-
-\--lt
-
-\--leq
-
-\--eq
-
-\--always
-
-args
+`nix-env` {`--upgrade` | `-u`} *args*
+  [`--lt` | `--leq` | `--eq` | `--always`]
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`}]
+  [`--from-expression`] [`-E`]
+  [`--from-profile` *path*]
+  [`--preserve-installed` | `-P`]
 
 ## Description
 
@@ -400,13 +354,13 @@ For the other flags, see `--install`.
 
     $ nix-env --upgrade gcc
     upgrading `gcc-3.3.1' to `gcc-3.4'
-    
+
     $ nix-env -u gcc-3.3.2 --always (switch to a specific version)
     upgrading `gcc-3.4' to `gcc-3.3.2'
-    
+
     $ nix-env --upgrade pan
     (no upgrades available, so nothing happens)
-    
+
     $ nix-env -u (try to upgrade everything)
     upgrading `hello-2.1.2' to `hello-2.1.3'
     upgrading `mozilla-1.2' to `mozilla-1.4'
@@ -451,19 +405,13 @@ This is illustrated by the following examples:
 
 ## Synopsis
 
-nix-env
-
-\--uninstall
-
-\-e
-
-drvnames
+`nix-env` {`--uninstall` | `-e`} *drvnames…*
 
 ## Description
 
 The uninstall operation creates a new user environment, based on the
 current generation of the active profile, from which the store paths
-designated by the symbolic names *names* are removed.
+designated by the symbolic names *drvnames* are removed.
 
 ## Examples
 
@@ -474,11 +422,7 @@ designated by the symbolic names *names* are removed.
 
 ## Synopsis
 
-nix-env
-
-\--set
-
-drvname
+`nix-env` `--set` *drvname*
 
 ## Description
 
@@ -496,15 +440,7 @@ contain just Firefox:
 
 ## Synopsis
 
-nix-env
-
-\--set-flag
-
-name
-
-value
-
-drvnames
+`nix-env` `--set-flag` *name* *value* *drvnames*
 
 ## Description
 
@@ -545,20 +481,20 @@ while the old remains part of the profile:
 
     $ nix-env -q
     firefox-2.0.0.9 (the current one)
-    
+
     $ nix-env --preserve-installed -i firefox-2.0.0.11
     installing `firefox-2.0.0.11'
     building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
     collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
       and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
     (i.e., can’t have two active at the same time)
-    
+
     $ nix-env --set-flag active false firefox
     setting flag on `firefox-2.0.0.9'
-    
+
     $ nix-env --preserve-installed -i firefox-2.0.0.11
     installing `firefox-2.0.0.11'
-    
+
     $ nix-env -q
     firefox-2.0.0.11 (the enabled one)
     firefox-2.0.0.9 (the disabled one)
@@ -572,57 +508,21 @@ To make files from `binutils` take precedence over files from `gcc`:
 
 ## Synopsis
 
-nix-env
-
-\--query
-
-\-q
-
-\--installed
-
-\--available
-
-\-a
-
-\--status
-
-\-s
-
-\--attr-path
-
-\-P
-
-\--no-name
-
-\--compare-versions
-
-\-c
-
-\--system
-
-\--drv-path
-
-\--out-path
-
-\--description
-
-\--meta
-
-\--xml
-
-\--json
-
-\--prebuilt-only
-
-\-b
-
-\--attr
-
-\-A
-
-attribute-path
-
-names
+`nix-env` {`--query` | `-q`} *names…*
+  [`--installed` | `--available` | `-a`]
+  [{`--status` | `-s`}]
+  [{`--attr-path` | `-P`}]
+  [`--no-name`]
+  [{`--compare-versions` | `-c`}]
+  [`--system`]
+  [`--drv-path`]
+  [`--out-path`]
+  [`--description`]
+  [`--meta`]
+  [`--xml`]
+  [`--json`]
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`} *attribute-path*]
 
 ## Description
 
@@ -696,17 +596,17 @@ derivation is shown unless `--no-name` is specified.
     `--available` is given). This is useful for quickly seeing whether
     upgrades for installed packages are available in a Nix expression. A
     column is added with the following meaning:
-    
+
       - `<` *version*  
         A newer version of the package is available or installed.
-    
+
       - `=` *version*  
         At most the same version of the package is available or
         installed.
-    
+
       - `>` *version*  
         Only older versions of the package are available or installed.
-    
+
       - `- ?`  
         No version of the package is available or installed.
 
@@ -797,13 +697,7 @@ To show all packages in the latest revision of the Nixpkgs repository:
 
 ## Synopsis
 
-nix-env
-
-\--switch-profile
-
-\-S
-
-path
+`nix-env` {`--switch-profile` | `-S`} *path*
 
 ## Description
 
@@ -818,9 +712,7 @@ the symlink `~/.nix-profile` is made to point to *path*.
 
 ## Synopsis
 
-nix-env
-
-\--list-generations
+`nix-env` `--list-generations`
 
 ## Description
 
@@ -841,11 +733,7 @@ generation, and indicates the current generation.
 
 ## Synopsis
 
-nix-env
-
-\--delete-generations
-
-generations
+`nix-env` `--delete-generations` *generations*
 
 ## Description
 
@@ -862,24 +750,18 @@ generations is important to make garbage collection effective.
 ## Examples
 
     $ nix-env --delete-generations 3 4 8
-    
+
     $ nix-env --delete-generations +5
-    
+
     $ nix-env --delete-generations 30d
-    
+
     $ nix-env -p other_profile --delete-generations old
 
 # Operation `--switch-generation`
 
 ## Synopsis
 
-nix-env
-
-\--switch-generation
-
-\-G
-
-generation
+`nix-env` {`--switch-generation` | `-G`} *generation*
 
 ## Description
 
@@ -900,9 +782,7 @@ Switching will fail if the specified generation does not exist.
 
 ## Synopsis
 
-nix-env
-
-\--rollback
+`nix-env` `--rollback`
 
 ## Description
 
@@ -915,7 +795,7 @@ generation, if it exists. It is just a convenience wrapper around
 
     $ nix-env --rollback
     switching from generation 92 to 91
-    
+
     $ nix-env --rollback
     error: no generation older than the current (91) exists
 
-- 
cgit v1.2.3


From da3d776cb91123a4d0528251b7ce909419ca0c7a Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Fri, 24 Jul 2020 14:31:33 +0200
Subject: Fix some dangling references

---
 doc/manual/src/command-ref/nix-env.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src/command-ref/nix-env.md')

diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index cf688100e..ab1d10c08 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -66,7 +66,7 @@ match. Here are some examples:
 
 This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
-have an effect. See also [???](#sec-common-options).
+have an effect.
 
   - `--file` / `-f` *path*  
     Specifies the Nix expression (designated below as the *active Nix
-- 
cgit v1.2.3


From 05a282295f3d454c811f9bdd9b755f6a5c07c190 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Fri, 24 Jul 2020 15:46:16 +0200
Subject: Fix internal links

---
 doc/manual/src/command-ref/nix-env.md | 37 ++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 18 deletions(-)

(limited to 'doc/manual/src/command-ref/nix-env.md')

diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index ab1d10c08..c5fcce316 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -92,7 +92,7 @@ have an effect.
     done if this flag had not been specified, without actually doing it.
 
     `--dry-run` also prints out which paths will be
-    [substituted](#gloss-substitute) (i.e., downloaded) and which paths
+    [substituted](../glossary.md) (i.e., downloaded) and which paths
     will be built from source (because no substitute is available).
 
   - `--system-filter` *system*  
@@ -186,11 +186,11 @@ a number of possible ways:
     gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
     probably cause a user environment conflict\!).
 
-  - If [`--attr`](#opt-attr) (`-A`) is specified, the arguments are
-    *attribute paths* that select attributes from the top-level Nix
+  - If `--attr` (`-A`) is specified, the arguments are *attribute
+    paths* that select attributes from the top-level Nix
     expression. This is faster than using derivation names and
-    unambiguous. To find out the attribute paths of available packages,
-    use `nix-env -qaP`.
+    unambiguous. To find out the attribute paths of available
+    packages, use `nix-env -qaP`.
 
   - If `--from-profile` *path* is given, *args* is a set of names
     denoting installed store paths in the profile *path*. This is an
@@ -198,18 +198,19 @@ a number of possible ways:
     another.
 
   - If `--from-expression` is given, *args* are Nix
-    [functions](#ss-functions) that are called with the active Nix
-    expression as their single argument. The derivations returned by
-    those function calls are installed. This allows derivations to be
-    specified in an unambiguous way, which is necessary if there are
-    multiple derivations with the same name.
+    [functions](../expressions/language-constructs.md#functions)
+    that are called with the active Nix expression as their single
+    argument. The derivations returned by those function calls are
+    installed. This allows derivations to be specified in an
+    unambiguous way, which is necessary if there are multiple
+    derivations with the same name.
 
   - If *args* are store derivations, then these are
-    [realised](#rsec-nix-store-realise), and the resulting output paths
+    [realised](nix-store.md#operation---realise), and the resulting output paths
     are installed.
 
   - If *args* are store paths that are not store derivations, then these
-    are [realised](#rsec-nix-store-realise) and installed.
+    are [realised](nix-store.md#operation---realise) and installed.
 
   - By default all outputs are installed for each derivation. That can
     be reduced by setting `meta.outputsToInstall`.
@@ -319,9 +320,9 @@ left untouched; this is not an error. It is also not an error if an
 element of *args* matches no installed derivations.
 
 For a description of how *args* is mapped to a set of store paths, see
-[`--install`](#rsec-nix-env-install). If *args* describes multiple store
-paths with the same symbolic name, only the one with the highest version
-is installed.
+[`--install`](#operation---install). If *args* describes multiple
+store paths with the same symbolic name, only the one with the highest
+version is installed.
 
 ## Flags
 
@@ -584,9 +585,9 @@ derivation is shown unless `--no-name` is specified.
 
   - `--attr-path`; `-P`  
     Print the *attribute path* of the derivation, which can be used to
-    unambiguously select it using the [`--attr` option](#opt-attr)
-    available in commands that install derivations like `nix-env
-    --install`. This option only works together with `--available`
+    unambiguously select it using the `--attr` option available in
+    commands that install derivations like `nix-env --install`. This
+    option only works together with `--available`
 
   - `--no-name`  
     Suppress printing of the `name` attribute of each derivation.
-- 
cgit v1.2.3


From 1d0a7b54fa330b041a720932ee4e05dcad1d2d5c Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Fri, 31 Jul 2020 15:43:25 +0200
Subject: Enable syntax highlighting

---
 doc/manual/src/command-ref/nix-env.md | 292 +++++++++++++++++++++-------------
 1 file changed, 183 insertions(+), 109 deletions(-)

(limited to 'doc/manual/src/command-ref/nix-env.md')

diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index c5fcce316..ee838581b 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -127,10 +127,12 @@ have an effect.
     For example, if `~/.nix-defexpr` contains two files, `foo.nix` and
     `bar.nix`, then the default Nix expression will essentially be
 
-        {
-          foo = import ~/.nix-defexpr/foo.nix;
-          bar = import ~/.nix-defexpr/bar.nix;
-        }
+    ```nix
+    {
+      foo = import ~/.nix-defexpr/foo.nix;
+      bar = import ~/.nix-defexpr/bar.nix;
+    }
+    ```
 
     The file `manifest.nix` is always ignored. Subdirectories without a
     `default.nix` file are traversed recursively in search of more Nix
@@ -240,44 +242,60 @@ a number of possible ways:
 
 To install a specific version of `gcc` from the active Nix expression:
 
-    $ nix-env --install gcc-3.3.2
-    installing `gcc-3.3.2'
-    uninstalling `gcc-3.1'
+```console
+$ nix-env --install gcc-3.3.2
+installing `gcc-3.3.2'
+uninstalling `gcc-3.1'
+```
 
 Note the previously installed version is removed, since
 `--preserve-installed` was not specified.
 
 To install an arbitrary version:
 
-    $ nix-env --install gcc
-    installing `gcc-3.3.2'
+```console
+$ nix-env --install gcc
+installing `gcc-3.3.2'
+```
 
 To install using a specific attribute:
 
-    $ nix-env -i -A gcc40mips
-    $ nix-env -i -A xorg.xorgserver
+```console
+$ nix-env -i -A gcc40mips
+$ nix-env -i -A xorg.xorgserver
+```
 
 To install all derivations in the Nix expression `foo.nix`:
 
-    $ nix-env -f ~/foo.nix -i '.*'
+```console
+$ nix-env -f ~/foo.nix -i '.*'
+```
 
 To copy the store path with symbolic name `gcc` from another profile:
 
-    $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
+```console
+$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
+```
 
 To install a specific store derivation (typically created by
 `nix-instantiate`):
 
-    $ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
+```console
+$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
+```
 
 To install a specific output path:
 
-    $ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
+```console
+$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
+```
 
 To install from a Nix expression specified on the command-line:
 
-    $ nix-env -f ./foo.nix -i -E \
-        'f: (f {system = "i686-linux";}).subversionWithJava'
+```console
+$ nix-env -f ./foo.nix -i -E \
+    'f: (f {system = "i686-linux";}).subversionWithJava'
+```
 
 I.e., this evaluates to `(f: (f {system =
 "i686-linux";}).subversionWithJava) (import ./foo.nix)`, thus selecting
@@ -286,17 +304,21 @@ function defined in `./foo.nix`.
 
 A dry-run tells you which paths will be downloaded or built from source:
 
-    $ nix-env -f '<nixpkgs>' -iA hello --dry-run
-    (dry run; not doing anything)
-    installing ‘hello-2.10’
-    this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
-      /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
-      ...
+```console
+$ nix-env -f '<nixpkgs>' -iA hello --dry-run
+(dry run; not doing anything)
+installing ‘hello-2.10’
+this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
+  /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
+  ...
+```
 
 To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12
 channel:
 
-    $ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
+```console
+$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
+```
 
 # Operation `--upgrade`
 
@@ -353,18 +375,26 @@ For the other flags, see `--install`.
 
 ## Examples
 
-    $ nix-env --upgrade gcc
-    upgrading `gcc-3.3.1' to `gcc-3.4'
+```console
+$ nix-env --upgrade gcc
+upgrading `gcc-3.3.1' to `gcc-3.4'
+```
 
-    $ nix-env -u gcc-3.3.2 --always (switch to a specific version)
-    upgrading `gcc-3.4' to `gcc-3.3.2'
+```console
+$ nix-env -u gcc-3.3.2 --always (switch to a specific version)
+upgrading `gcc-3.4' to `gcc-3.3.2'
+```
 
-    $ nix-env --upgrade pan
-    (no upgrades available, so nothing happens)
+```console
+$ nix-env --upgrade pan
+(no upgrades available, so nothing happens)
+```
 
-    $ nix-env -u (try to upgrade everything)
-    upgrading `hello-2.1.2' to `hello-2.1.3'
-    upgrading `mozilla-1.2' to `mozilla-1.4'
+```console
+$ nix-env -u (try to upgrade everything)
+upgrading `hello-2.1.2' to `hello-2.1.3'
+upgrading `mozilla-1.2' to `mozilla-1.4'
+```
 
 ## Versions
 
@@ -416,8 +446,10 @@ designated by the symbolic names *drvnames* are removed.
 
 ## Examples
 
-    $ nix-env --uninstall gcc
-    $ nix-env -e '.*' (remove everything)
+```console
+$ nix-env --uninstall gcc
+$ nix-env -e '.*' (remove everything)
+```
 
 # Operation `--set`
 
@@ -435,7 +467,9 @@ that it contains exactly the specified derivation, and nothing else.
 The following updates a profile such that its current generation will
 contain just Firefox:
 
-    $ nix-env -p /nix/var/nix/profiles/browser --set firefox
+```console
+$ nix-env -p /nix/var/nix/profiles/browser --set firefox
+```
 
 # Operation `--set-flag`
 
@@ -473,37 +507,43 @@ environment build script:
 
 To prevent the currently installed Firefox from being upgraded:
 
-    $ nix-env --set-flag keep true firefox
+```console
+$ nix-env --set-flag keep true firefox
+```
 
 After this, `nix-env -u` will ignore Firefox.
 
 To disable the currently installed Firefox, then install a new Firefox
 while the old remains part of the profile:
 
-    $ nix-env -q
-    firefox-2.0.0.9 (the current one)
+```console
+$ nix-env -q
+firefox-2.0.0.9 (the current one)
 
-    $ nix-env --preserve-installed -i firefox-2.0.0.11
-    installing `firefox-2.0.0.11'
-    building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
-    collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
-      and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
-    (i.e., can’t have two active at the same time)
+$ nix-env --preserve-installed -i firefox-2.0.0.11
+installing `firefox-2.0.0.11'
+building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
+collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
+  and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
+(i.e., can’t have two active at the same time)
 
-    $ nix-env --set-flag active false firefox
-    setting flag on `firefox-2.0.0.9'
+$ nix-env --set-flag active false firefox
+setting flag on `firefox-2.0.0.9'
 
-    $ nix-env --preserve-installed -i firefox-2.0.0.11
-    installing `firefox-2.0.0.11'
+$ nix-env --preserve-installed -i firefox-2.0.0.11
+installing `firefox-2.0.0.11'
 
-    $ nix-env -q
-    firefox-2.0.0.11 (the enabled one)
-    firefox-2.0.0.9 (the disabled one)
+$ nix-env -q
+firefox-2.0.0.11 (the enabled one)
+firefox-2.0.0.9 (the disabled one)
+```
 
 To make files from `binutils` take precedence over files from `gcc`:
 
-    $ nix-env --set-flag priority 5 binutils
-    $ nix-env --set-flag priority 10 gcc
+```console
+$ nix-env --set-flag priority 5 binutils
+$ nix-env --set-flag priority 10 gcc
+```
 
 # Operation `--query`
 
@@ -633,66 +673,82 @@ derivation is shown unless `--no-name` is specified.
 
 To show installed packages:
 
-    $ nix-env -q
-    bison-1.875c
-    docbook-xml-4.2
-    firefox-1.0.4
-    MPlayer-1.0pre7
-    ORBit2-2.8.3
-    …
+```console
+$ nix-env -q
+bison-1.875c
+docbook-xml-4.2
+firefox-1.0.4
+MPlayer-1.0pre7
+ORBit2-2.8.3
+…
+```
 
 To show available packages:
 
-    $ nix-env -qa
-    firefox-1.0.7
-    GConf-2.4.0.1
-    MPlayer-1.0pre7
-    ORBit2-2.8.3
-    …
+```console
+$ nix-env -qa
+firefox-1.0.7
+GConf-2.4.0.1
+MPlayer-1.0pre7
+ORBit2-2.8.3
+…
+```
 
 To show the status of available packages:
 
-    $ nix-env -qas
-    -P- firefox-1.0.7   (not installed but present)
-    --S GConf-2.4.0.1   (not present, but there is a substitute for fast installation)
-    --S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
-    IP- ORBit2-2.8.3    (installed and by definition present)
-    …
+```console
+$ nix-env -qas
+-P- firefox-1.0.7   (not installed but present)
+--S GConf-2.4.0.1   (not present, but there is a substitute for fast installation)
+--S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
+IP- ORBit2-2.8.3    (installed and by definition present)
+…
+```
 
 To show available packages in the Nix expression `foo.nix`:
 
-    $ nix-env -f ./foo.nix -qa
-    foo-1.2.3
+```console
+$ nix-env -f ./foo.nix -qa
+foo-1.2.3
+```
 
 To compare installed versions to what’s available:
 
-    $ nix-env -qc
-    ...
-    acrobat-reader-7.0 - ?      (package is not available at all)
-    autoconf-2.59      = 2.59   (same version)
-    firefox-1.0.4      < 1.0.7  (a more recent version is available)
-    ...
+```console
+$ nix-env -qc
+...
+acrobat-reader-7.0 - ?      (package is not available at all)
+autoconf-2.59      = 2.59   (same version)
+firefox-1.0.4      < 1.0.7  (a more recent version is available)
+...
+```
 
 To show all packages with “`zip`” in the name:
 
-    $ nix-env -qa '.*zip.*'
-    bzip2-1.0.6
-    gzip-1.6
-    zip-3.0
-    …
+```console
+$ nix-env -qa '.*zip.*'
+bzip2-1.0.6
+gzip-1.6
+zip-3.0
+…
+```
 
 To show all packages with “`firefox`” or “`chromium`” in the name:
 
-    $ nix-env -qa '.*(firefox|chromium).*'
-    chromium-37.0.2062.94
-    chromium-beta-38.0.2125.24
-    firefox-32.0.3
-    firefox-with-plugins-13.0.1
-    …
+```console
+$ nix-env -qa '.*(firefox|chromium).*'
+chromium-37.0.2062.94
+chromium-beta-38.0.2125.24
+firefox-32.0.3
+firefox-with-plugins-13.0.1
+…
+```
 
 To show all packages in the latest revision of the Nixpkgs repository:
 
-    $ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
+```console
+$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
+```
 
 # Operation `--switch-profile`
 
@@ -707,7 +763,9 @@ the symlink `~/.nix-profile` is made to point to *path*.
 
 ## Examples
 
-    $ nix-env -S ~/my-profile
+```console
+$ nix-env -S ~/my-profile
+```
 
 # Operation `--list-generations`
 
@@ -724,11 +782,13 @@ generation, and indicates the current generation.
 
 ## Examples
 
-    $ nix-env --list-generations
-      95   2004-02-06 11:48:24
-      96   2004-02-06 11:49:01
-      97   2004-02-06 16:22:45
-      98   2004-02-06 16:24:33   (current)
+```console
+$ nix-env --list-generations
+  95   2004-02-06 11:48:24
+  96   2004-02-06 11:49:01
+  97   2004-02-06 16:22:45
+  98   2004-02-06 16:24:33   (current)
+```
 
 # Operation `--delete-generations`
 
@@ -750,13 +810,21 @@ generations is important to make garbage collection effective.
 
 ## Examples
 
-    $ nix-env --delete-generations 3 4 8
+```console
+$ nix-env --delete-generations 3 4 8
+```
 
-    $ nix-env --delete-generations +5
+```console
+$ nix-env --delete-generations +5
+```
 
-    $ nix-env --delete-generations 30d
+```console
+$ nix-env --delete-generations 30d
+```
 
-    $ nix-env -p other_profile --delete-generations old
+```console
+$ nix-env -p other_profile --delete-generations old
+```
 
 # Operation `--switch-generation`
 
@@ -776,8 +844,10 @@ Switching will fail if the specified generation does not exist.
 
 ## Examples
 
-    $ nix-env -G 42
-    switching from generation 50 to 42
+```console
+$ nix-env -G 42
+switching from generation 50 to 42
+```
 
 # Operation `--rollback`
 
@@ -794,11 +864,15 @@ generation, if it exists. It is just a convenience wrapper around
 
 ## Examples
 
-    $ nix-env --rollback
-    switching from generation 92 to 91
+```console
+$ nix-env --rollback
+switching from generation 92 to 91
+```
 
-    $ nix-env --rollback
-    error: no generation older than the current (91) exists
+```console
+$ nix-env --rollback
+error: no generation older than the current (91) exists
+```
 
 # Environment variables
 
-- 
cgit v1.2.3