Nix: update and add documentation for nix subcommands (#9959)

* Nix: update and add documentation for nix subcommands

Updates the documentation on the new unstable Nix command & subcommands,
and adds a separate page for the Classic Nix commands.

---------

Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: axtloss <axtlos@getcryst.al>
Co-authored-by: CleanMachine1 <78213164+CleanMachine1@users.noreply.github.com>

pages/common/nix-build.md

@@ -1,7 +1,8 @@
 # nix-build
 
 > Build a Nix expression.
-> More information: <https://nixos.org/releases/nix/latest/manual#sec-nix-build>.
+> See also: `tldr nix3 build`.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/nix-build.html>.
 
 - Build a Nix expression:
 

pages/common/nix-classic.md

@@ -0,0 +1,29 @@
+# Nix classic interface
+
+> A classic, stable interface to a powerful package manager that makes package management reliable, reproducible, and declarative.
+> Some Nix commands such as `nix-build`, `nix-shell`, `nix-env`, and `nix-store` have their own pages. See also: `tldr nix`.
+> More information: <https://nixos.org>.
+
+- Search for a package in nixpkgs via its name:
+
+`nix-env -qaP {{search_term_regexp}}`
+
+- Start a shell with the specified packages available:
+
+`nix-shell -p {{pkg1 pkg2 pkg3...}}`
+
+- Install some packages permanently:
+
+`nix-env -iA {{nixpkgs.pkg1 nixpkgs.pkg2...}}`
+
+- Show all dependencies of a store path (package), in a tree format:
+
+`nix-store --query --tree {{/nix/store/...}}`
+
+- Update the channels (repositories):
+
+`nix-channel --update`
+
+- Remove unused paths from Nix store:
+
+`nix-collect-garbage`

pages/common/nix-shell.md

@@ -1,7 +1,8 @@
 # nix-shell
 
 > Start an interactive shell based on a Nix expression.
-> More information: <https://nixos.org/manual/nix/stable/#sec-nix-shell>.
+> See also: `tldr nix3 shell`.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/nix-shell.html>.
 
 - Start with nix expression in `shell.nix` or `default.nix` in the current directory:
 

pages/common/nix-store.md

@@ -0,0 +1,29 @@
+# nix-store
+
+> Manipulate or query the Nix store.
+> See also: `tldr nix3 store`.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/nix-store.html>.
+
+- Collect garbage, such as removing unused paths:
+
+`nix-store --gc`
+
+- Hard-link identical files together to reduce space usage:
+
+`nix-store --optimise`
+
+- Delete a specific store path (must be unused):
+
+`nix-store --delete {{/nix/store/...}}`
+
+- Show all dependencies of a store path (package), in a tree format:
+
+`nix-store --query --tree {{/nix/store/...}}`
+
+- Calculate the total size of a certain store path with all the dependencies:
+
+`du -cLsh $(nix-store --query --references {{/nix/store/...}})`
+
+- Show all dependents of a particular store path:
+
+`nix-store --query --referrers {{/nix/store/...}}`

pages/common/nix.md

@@ -1,24 +1,34 @@
 # nix
 
-> Utilities for the Nix language and store.
-> More information: <https://nixos.org>.
+> Powerful package manager that makes package management reliable, reproducible, and declarative.
+> The `nix` command-line utility is experimental and requires enabling experimental features. For a classic, stable interface, see `tldr nix classic`.
+> Some `nix` subcommands such as `build`, `develop`, `flake`, `registry`, `profile`, `search`, `repl`, `store`, `edit`, `why-depends` etc. have their own usage documentation, accessible via `tldr nix3 subcommand`.
+> More information: <https://nixos.org/manual/nix>.
 
-- Search for a package via its name or description:
+- Enable the `nix` command:
 
-`nix search {{search_term}}`
+`mkdir -p ~/.config/nix; echo 'experimental-features = nix-command flakes' > ~/.config/nix/nix.conf`
 
-- Start a Nix shell with the specified packages available:
+- Display help for the `nix` subcommand:
 
-`nix run {{nixpkgs.pkg1 nixpkgs.pkg2 nixpkgs.pkg3...}}`
+`nix help {{subcommand}}`
 
-- Optimise Nix store disk usage by combining duplicate files:
+- Search for a package in nixpkgs via its name or description:
 
-`nix store optimise`
+`nix search nixpkgs {{search_term}}`
+
+- Start a shell with the specified packages from nixpkgs available:
+
+`nix shell {{nixpkgs#pkg1 nixpkgs#pkg2 nixpkgs#pkg3 ...}}`
+
+- Install some packages from nixpkgs permanently:
+
+`nix profile install {{nixpkgs#pkg1 nixpkgs#pkg2 nixpkgs#pkg3 ...}}`
+
+- Remove unused paths from Nix store to free up space:
+
+`nix store gc`
 
 - Start an interactive environment for evaluating Nix expressions:
 
 `nix repl`
-
-- Upgrade Nix to the latest stable version:
-
-`nix upgrade-nix`

pages/common/nix3-build.md

@@ -0,0 +1,21 @@
+# nix build
+
+> Build a Nix expression (downloading from the cache when possible).
+> See also: `tldr nix-build`. See `tldr nix3 flake` for information about flakes.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html>.
+
+- Build a package from nixpkgs, symlinking the result to `./result`:
+
+`nix build {{nixpkgs#pkg}}`
+
+- Build a package from a flake in the current directory, showing the build logs in the process:
+
+`nix build -L {{.#pkg}}`
+
+- Build the default package from a flake in some directory:
+
+`nix build {{./path/to/directory}}`
+
+- Build a package without making the `result` symlink, instead printing the store path to the stdout:
+
+`nix build --no-link --print-out-paths`

pages/common/nix3-develop.md

@@ -0,0 +1,16 @@
+# nix develop
+
+> Run a bash shell that provides the build environment of a derivation.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html>.
+
+- Start a shell with all dependencies of a package from nixpkgs available:
+
+`nix develop {{nixpkgs#pkg}}`
+
+- Start a development shell for the default package in a flake in the current directory:
+
+`nix develop`
+
+- In that shell, configure and build the sources:
+
+`configurePhase; buildPhase`

pages/common/nix3-edit.md

@@ -0,0 +1,12 @@
+# nix edit
+
+> Open the Nix expression of a Nix package in $EDITOR.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-edit.html>.
+
+- Open the source of the Nix expression of a package from nixpkgs in your `$EDITOR`:
+
+`nix edit {{nixpkgs#pkg}}`
+
+- Dump the source of a package to stdout:
+
+`EDITOR=cat nix edit {{nixpkgs#pkg}}`

pages/common/nix3-flake.md

@@ -0,0 +1,24 @@
+# nix flake
+
+> Manage Nix flakes.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html>.
+
+- See documentation about what Nix flakes are:
+
+`nix flake --help`
+
+- Create a new flake (just the `flake.nix` file) from the default template, in the current directory:
+
+`nix flake init`
+
+- Update all inputs (dependencies) of the flake in the current directory:
+
+`nix flake update`
+
+- Update a specific input (dependency) of the flake in the current directory:
+
+`nix flake lock --update-input {{input}}`
+
+- Show all the outputs of a flake on github:
+
+`nix flake show {{github:owner/repo}}`

pages/common/nix3-profile.md

@@ -0,0 +1,28 @@
+# nix profile
+
+> Install, update and remove packages from Nix profiles.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-profile.html>.
+
+- Install some packages from nixpkgs into the default profile:
+
+`nix profile install {{nixpkgs#pkg1 nixpkgs#pkg2 ...}}`
+
+- Install a package from a flake on GitHub into a custom profile:
+
+`nix profile install {{github:owner/repo/pkg}} --profile {{./path/to/directory}}`
+
+- List packages currently installed in the default profile:
+
+`nix profile list`
+
+- Remove a package installed from nixpkgs from the default profile, by name:
+
+`nix profile remove {{legacyPackages.x86_64-linux.pkg}}`
+
+- Upgrade packages in the default to the latest available versions:
+
+`nix profile upgrade`
+
+- Rollback (cancel) the latest action on the default profile:
+
+`nix profile rollback`

pages/common/nix3-registry.md

@@ -0,0 +1,25 @@
+# nix registry
+
+> Manage a Nix flake registry.
+> See `tldr nix3 flake` for information about flakes.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html>.
+
+- Pin the `nixpkgs` revision to the current version of the upstream repository:
+
+`nix registry pin {{nixpkgs}}`
+
+- Pin an entry to the latest version of the branch, or a particular reivision of a github repository:
+
+`nix registry pin {{entry}} {{github:owner/repo/branch_or_revision}}`
+
+- Add a new entry that always points to the latest version of a github repository, updating automatically:
+
+`nix registry add {{entry}} {{github:owner/repo}}`
+
+- Remove a registry entry:
+
+`nix registry remove {{entry}}`
+
+- See documentation about what Nix flake registries are:
+
+`nix registry --help`

pages/common/nix3-repl.md

@@ -0,0 +1,25 @@
+# nix repl
+
+> Start an interactive environment for evaluating Nix expressions.
+> See <https://nixos.org/manual/nix/stable/language/index.html> for a description of the Nix expression language.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl.html>.
+
+- Start an interactive environment for evaluating Nix expressions:
+
+`nix repl`
+
+- Load all packages from a flake (e.g. `nixpkgs`) into scope:
+
+`:lf {{nixpkgs}}`
+
+- Build a package from an expression:
+
+`:b {{expression}}`
+
+- Start a shell with package from the expression available:
+
+`:u {{expression}}`
+
+- Start a shell with dependencies of the package from the expression available:
+
+`:s {{expression}}`

pages/common/nix3-run.md

@@ -0,0 +1,13 @@
+# nix run
+
+> Run an application from a Nix flake.
+> See `tldr nix3 flake` for information about flakes.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run.html>.
+
+- Run a command whose name matches the package name from nixpkgs (if you want a different command from that package, see `tldr nix3 shell`):
+
+`nix run nixpkgs#{{pkg}}`
+
+- Run the default application in the flake in the current directory:
+
+`nix run`

pages/common/nix3-search.md

@@ -0,0 +1,17 @@
+# nix search
+
+> Search for packages in a Nix flake.
+> See `tldr nix3 flake` for information about flakes.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-search.html>.
+
+- Search `nixpkgs` for a package based on its name or description:
+
+`nix search {{nixpkgs}} {{search_term...}}`
+
+- Show description of a package from nixpkgs:
+
+`nix search {{nixpkgs#pkg}}`
+
+- Show all packages available from a flake on github:
+
+`nix search {{github:owner/repo}}`

pages/common/nix3-shell.md

@@ -0,0 +1,25 @@
+# nix shell
+
+> Start a shell in which the specified packages are available.
+> See also: `tldr nix-shell`. See `tldr nix3 flake` for information about flakes.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-shell.html>.
+
+- Start an interactive shell with some packages from `nixpkgs`:
+
+`nix shell {{nixpkgs#pkg1 nixpkgs#packageSet.pkg2 ...}}`
+
+- Start a shell providing a package from an older version of `nixpkgs` (21.05):
+
+`nix shell {{nixpkgs/nixos-21.05#pkg}}`
+
+- Start a shell with the "default package" from a flake in the current directory, printing build logs if any builds happen:
+
+`nix shell -L`
+
+- Start a shell with a package from a flake on GitHub:
+
+`nix shell {{github:owner/repo#pkg}}`
+
+- Run a command in a shell with a package:
+
+`nix shell {{nixpkgs#pkg}} -c {{some-cmd --someflag 'Some other arguments'}}`

pages/common/nix3-store.md

@@ -0,0 +1,25 @@
+# nix store
+
+> Manipulate the Nix store.
+> See also: `tldr nix-store`.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-store.html>.
+
+- Collect garbage, i.e. remove unused paths to reduce space usage:
+
+`nix store gc`
+
+- Hard-link identical files together to reduce space usage:
+
+`nix store optimise`
+
+- Delete a specific store path (most be unused):
+
+`nix store delete {{/nix/store/...}}`
+
+- List a contents of the store path, on a remote store:
+
+`nix store --store {{https://cache.nixos.org}} ls {{/nix/store/...}}`
+
+- Show the differences in versions between two store paths, with their respective dependencies:
+
+`nix store diff-closures {{/nix/store/...}} {{/nix/store/...}}`

pages/common/nix3-why-depends.md

@@ -0,0 +1,12 @@
+# nix why-depends
+
+> Show why a package depends on another package.
+> More information: <https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-why-depends.html>.
+
+- Show why the currently running NixOS system requires a certain store path:
+
+`nix why-depends {{/run/current-system}} {{/nix/store/...}}`
+
+- Show why a package from nixpkgs requires another package as a _build-time_ dependency:
+
+`nix why-depends --derivation {{nixpkgs#dependent}} {{nixpkgs#dependency}}`