From de3f5106ada4cb8b2c22e62e4c54eb82e3fa8706 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 04:22:00 +0200 Subject: [PATCH 1/8] remove superfluous phrase it may actually mislead people about what "cleaning up your system" could mean. removing it does not distort the original intent. --- doc/manual/src/command-ref/nix-collect-garbage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md index 3cab79f0eba5..809166f22e6d 100644 --- a/doc/manual/src/command-ref/nix-collect-garbage.md +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -9,7 +9,7 @@ # Description The command `nix-collect-garbage` is mostly an alias of [`nix-store --gc`](@docroot@/command-ref/nix-store/gc.md). -That is, it deletes all unreachable [store objects] in the Nix store to clean up your system. +That is, it deletes all unreachable [store objects] in the Nix store. However, it provides two additional options, [`--delete-old`](#opt-delete-old) and [`--delete-older-than`](#opt-delete-older-than), From 43bf51f4ea7a5aebc4109bb1f2f4ae463572914d Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 04:23:02 +0200 Subject: [PATCH 2/8] move warning into the list item contents this makes it easier to see the actual locations the command inspects. reword the note to be more on point. --- doc/manual/src/command-ref/nix-collect-garbage.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md index 809166f22e6d..7dd82094aef4 100644 --- a/doc/manual/src/command-ref/nix-collect-garbage.md +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -32,15 +32,14 @@ Instead, it looks in a few locations, and acts on all profiles it finds there: 1. The default profile locations as specified in the [profiles] section of the manual. -2. > **NOTE** - > - > Not stable; subject to change +2. `$NIX_STATE_DIR/profiles` and `$NIX_STATE_DIR/profiles/per-user` + + > **Warning** > - > Do not rely on this functionality; it just exists for migration purposes and is may change in the future. + > Do not rely on this functionality! + > It only exists for migration purposes and may change in the future. > These deprecated paths remain a private implementation detail of Nix. - `$NIX_STATE_DIR/profiles` and `$NIX_STATE_DIR/profiles/per-user`. - With the exception of `$NIX_STATE_DIR/profiles/per-user/root` and `$NIX_STATE_DIR/profiles/default`, these directories are no longer used by other commands. `nix-collect-garbage` looks there anyways in order to clean up profiles from older versions of Nix. From eec22e70fddd009f000c8bcf085c6e83ca9af97c Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 04:24:18 +0200 Subject: [PATCH 3/8] dedent lists --- doc/manual/src/command-ref/nix-store/gc.md | 44 ++++++++++++---------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/gc.md b/doc/manual/src/command-ref/nix-store/gc.md index 7be0d559add3..f432e00eb96b 100644 --- a/doc/manual/src/command-ref/nix-store/gc.md +++ b/doc/manual/src/command-ref/nix-store/gc.md @@ -14,30 +14,34 @@ reachable via file system references from a set of “roots”, are deleted. The following suboperations may be specified: - - `--print-roots`\ - This operation prints on standard output the set of roots used by - the garbage collector. - - - `--print-live`\ - This operation prints on standard output the set of “live” store - paths, which are all the store paths reachable from the roots. Live - paths should never be deleted, since that would break consistency — - it would become possible that applications are installed that - reference things that are no longer present in the store. - - - `--print-dead`\ - This operation prints out on standard output the set of “dead” store - paths, which is just the opposite of the set of live paths: any path - in the store that is not live (with respect to the roots) is dead. +- `--print-roots` + + This operation prints on standard output the set of roots used by + the garbage collector. + +- `--print-live` + + This operation prints on standard output the set of “live” store + paths, which are all the store paths reachable from the roots. Live + paths should never be deleted, since that would break consistency — + it would become possible that applications are installed that + reference things that are no longer present in the store. + +- `--print-dead` + + This operation prints out on standard output the set of “dead” store + paths, which is just the opposite of the set of live paths: any path + in the store that is not live (with respect to the roots) is dead. By default, all unreachable paths are deleted. The following options control what gets deleted and in what order: - - `--max-freed` *bytes*\ - Keep deleting paths until at least *bytes* bytes have been deleted, - then stop. The argument *bytes* can be followed by the - multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB - or TiB units. +- `--max-freed` *bytes* + + Keep deleting paths until at least *bytes* bytes have been deleted, + then stop. The argument *bytes* can be followed by the + multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB + or TiB units. The behaviour of the collector is also influenced by the `keep-outputs` and `keep-derivations` settings in the Nix From 1e7d23db170937d289b63bfa65d1e16add7999a6 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 04:24:42 +0200 Subject: [PATCH 4/8] "roots" -> garbage collection roots this is a fixed technical term, no need to quote it as if it were something hypothetical --- doc/manual/src/command-ref/nix-store/gc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/gc.md b/doc/manual/src/command-ref/nix-store/gc.md index f432e00eb96b..f00d6a7934ba 100644 --- a/doc/manual/src/command-ref/nix-store/gc.md +++ b/doc/manual/src/command-ref/nix-store/gc.md @@ -10,7 +10,7 @@ Without additional flags, the operation `--gc` performs a garbage collection on the Nix store. That is, all paths in the Nix store not -reachable via file system references from a set of “roots”, are deleted. +reachable via file system references from a set of gargbage collection roots, are deleted. The following suboperations may be specified: From 623207b32bcd27c966df6350e22c5842be61770b Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 04:25:24 +0200 Subject: [PATCH 5/8] use imperative in examples --- doc/manual/src/command-ref/nix-store/gc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/gc.md b/doc/manual/src/command-ref/nix-store/gc.md index f00d6a7934ba..5bcd154251d7 100644 --- a/doc/manual/src/command-ref/nix-store/gc.md +++ b/doc/manual/src/command-ref/nix-store/gc.md @@ -59,7 +59,7 @@ number of bytes that would be freed. # Examples -To delete all unreachable paths, just do: +Delete all unreachable paths: ```console $ nix-store --gc @@ -68,7 +68,7 @@ deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv' 8825586 bytes freed (8.42 MiB) ``` -To delete at least 100 MiBs of unreachable paths: +Delete at least 100 MiBs of unreachable paths: ```console $ nix-store --gc --max-freed $((100 * 1024 * 1024)) From 87ba5e2d0a28320c9c9b34eb0c62d5ff26567244 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 04:29:13 +0200 Subject: [PATCH 6/8] add links --- doc/manual/src/command-ref/nix-store/gc.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/gc.md b/doc/manual/src/command-ref/nix-store/gc.md index 5bcd154251d7..c4033a551c16 100644 --- a/doc/manual/src/command-ref/nix-store/gc.md +++ b/doc/manual/src/command-ref/nix-store/gc.md @@ -43,9 +43,7 @@ control what gets deleted and in what order: multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB or TiB units. -The behaviour of the collector is also influenced by the -`keep-outputs` and `keep-derivations` settings in the Nix -configuration file. +The behaviour of the garbage collector is also influenced by the [`keep-outputs`](@docroot@/command-ref/conf-file.md#conf-keep-outputs) and [`keep-derivations`] (@docroot@/command-ref/conf-file.md#conf-keep-derivations) configuration settings. By default, the collector prints the total number of freed bytes when it finishes (or when it is interrupted). With `--print-dead`, it prints the From f42bfe7248b6ca2e0de887ec614c1decc37f2226 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 04:44:12 +0200 Subject: [PATCH 7/8] move all unique information on garbage collection to `nix-store --gc` --- doc/manual/src/SUMMARY.md.in | 2 - doc/manual/src/command-ref/nix-store/gc.md | 26 +++++-- .../package-management/garbage-collection.md | 73 ------------------- .../garbage-collector-roots.md | 18 ----- 4 files changed, 21 insertions(+), 98 deletions(-) delete mode 100644 doc/manual/src/package-management/garbage-collection.md delete mode 100644 doc/manual/src/package-management/garbage-collector-roots.md diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index e49e77cf548b..2ca62f8f5018 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -19,8 +19,6 @@ - [Package Management](package-management/package-management.md) - [Basic Package Management](package-management/basic-package-mgmt.md) - [Profiles](package-management/profiles.md) - - [Garbage Collection](package-management/garbage-collection.md) - - [Garbage Collector Roots](package-management/garbage-collector-roots.md) - [Sharing Packages Between Machines](package-management/sharing-packages.md) - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md) - [Copying Closures via SSH](package-management/copy-closure.md) diff --git a/doc/manual/src/command-ref/nix-store/gc.md b/doc/manual/src/command-ref/nix-store/gc.md index c4033a551c16..c3f5ff9770d0 100644 --- a/doc/manual/src/command-ref/nix-store/gc.md +++ b/doc/manual/src/command-ref/nix-store/gc.md @@ -8,9 +8,8 @@ # Description -Without additional flags, the operation `--gc` performs a garbage -collection on the Nix store. That is, all paths in the Nix store not -reachable via file system references from a set of gargbage collection roots, are deleted. +Without additional flags, the operation `--gc` performs a garbage collection on the Nix store. +That is, all paths in the Nix store not reachable via file system references from a set of [gargbage collector roots](#garbage-collector-roots), are deleted. The following suboperations may be specified: @@ -43,12 +42,29 @@ control what gets deleted and in what order: multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB or TiB units. -The behaviour of the garbage collector is also influenced by the [`keep-outputs`](@docroot@/command-ref/conf-file.md#conf-keep-outputs) and [`keep-derivations`] (@docroot@/command-ref/conf-file.md#conf-keep-derivations) configuration settings. - By default, the collector prints the total number of freed bytes when it finishes (or when it is interrupted). With `--print-dead`, it prints the number of bytes that would be freed. +## Garbage collector roots + +Garbage collector roots are all store paths to which there are symlinks in the directory `/nix/var/nix/gcroots`. + +> **Example** +> +> The following command makes the path `/nix/store/d718ef...-foo` a root of the collector: +> +> ```console +> $ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar +> ``` +> +> That is, after this command, the garbage collector will not remove `/nix/store/d718ef...-foo` or any of its dependencies. + +Subdirectories of `/nix/var/nix/gcroots` are also searched for symlinks. +Symlinks to paths outside the Nix store are followed and searched for roots, but only one level deep to prevent infinite recursion. + +The behaviour of the garbage collector is also influenced by the [`keep-outputs`](@docroot@/command-ref/conf-file.md#conf-keep-outputs) and [`keep-derivations`] (@docroot@/command-ref/conf-file.md#conf-keep-derivations) configuration settings. + {{#include ./opt-common.md}} {{#include ../opt-common.md}} diff --git a/doc/manual/src/package-management/garbage-collection.md b/doc/manual/src/package-management/garbage-collection.md deleted file mode 100644 index 29a3b3101490..000000000000 --- a/doc/manual/src/package-management/garbage-collection.md +++ /dev/null @@ -1,73 +0,0 @@ -# Garbage Collection - -`nix-env` operations such as upgrades (`-u`) and uninstall (`-e`) never -actually delete packages from the system. All they do (as shown above) -is to create a new user environment that no longer contains symlinks to -the “deleted” packages. - -Of course, since disk space is not infinite, unused packages should be -removed at some point. You can do this by running the Nix garbage -collector. It will remove from the Nix store any package not used -(directly or indirectly) by any generation of any profile. - -Note however that as long as old generations reference a package, it -will not be deleted. After all, we wouldn’t be able to do a rollback -otherwise. So in order for garbage collection to be effective, you -should also delete (some) old generations. Of course, this should only -be done if you are certain that you will not need to roll back. - -To delete all old (non-current) generations of your current profile: - -```console -$ nix-env --delete-generations old -``` - -Instead of `old` you can also specify a list of generations, e.g., - -```console -$ nix-env --delete-generations 10 11 14 -``` - -To delete all generations older than a specified number of days (except -the current generation), use the `d` suffix. For example, - -```console -$ nix-env --delete-generations 14d -``` - -deletes all generations older than two weeks. - -After removing appropriate old generations you can run the garbage -collector as follows: - -```console -$ nix-store --gc -``` - -The behaviour of the garbage collector is affected by the -`keep-derivations` (default: true) and `keep-outputs` (default: false) -options in the Nix configuration file. The defaults will ensure that all -derivations that are build-time dependencies of garbage collector roots -will be kept and that all output paths that are runtime dependencies -will be kept as well. All other derivations or paths will be collected. -(This is usually what you want, but while you are developing it may make -sense to keep outputs to ensure that rebuild times are quick.) If you -are feeling uncertain, you can also first view what files would be -deleted: - -```console -$ nix-store --gc --print-dead -``` - -Likewise, the option `--print-live` will show the paths that *won’t* be -deleted. - -There is also a convenient little utility `nix-collect-garbage`, which -when invoked with the `-d` (`--delete-old`) switch deletes all old -generations of all profiles in `/nix/var/nix/profiles`. So - -```console -$ nix-collect-garbage -d -``` - -is a quick and easy way to clean up your system. diff --git a/doc/manual/src/package-management/garbage-collector-roots.md b/doc/manual/src/package-management/garbage-collector-roots.md deleted file mode 100644 index 30c5b7f8ddcd..000000000000 --- a/doc/manual/src/package-management/garbage-collector-roots.md +++ /dev/null @@ -1,18 +0,0 @@ -# Garbage Collector Roots - -The roots of the garbage collector are all store paths to which there -are symlinks in the directory `prefix/nix/var/nix/gcroots`. For -instance, the following command makes the path -`/nix/store/d718ef...-foo` a root of the collector: - -```console -$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar -``` - -That is, after this command, the garbage collector will not remove -`/nix/store/d718ef...-foo` or any of its dependencies. - -Subdirectories of `prefix/nix/var/nix/gcroots` are also searched for -symlinks. Symlinks to non-store paths are followed and searched for -roots, but symlinks to non-store paths *inside* the paths reached in -that way are not followed to prevent infinite recursion. From d5e65340f614895bb091bcf67ff95402eb359b79 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 23 Oct 2023 05:41:50 +0200 Subject: [PATCH 8/8] fix broken link --- doc/manual/src/package-management/profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/package-management/profiles.md b/doc/manual/src/package-management/profiles.md index 1d9e672a8def..29f9af041d51 100644 --- a/doc/manual/src/package-management/profiles.md +++ b/doc/manual/src/package-management/profiles.md @@ -120,7 +120,7 @@ These commands switch to the `my-profile` and default profile, respectively. If the profile doesn’t exist, it will be created automatically. You should be careful about storing a profile in another location than the `profiles` directory, since otherwise it might not be -used as a root of the [garbage collector](garbage-collection.md). +used as a root of the [garbage collector](@docroot@/command-ref/nix-store/gc.md). All `nix-env` operations work on the profile pointed to by `~/.nix-profile`, but you can override this using the `--profile` option