From 5cc22e337023cee9cbffd3f9d2ff0eb3f18a4d12 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Thu, 15 Jun 2023 22:29:03 -0400 Subject: [PATCH] Clarify docs on deleting generations, including fixing a mistake Deleting store info corrected (there is a foot-gun in Nix with `--delete-generations old`!) Also a few things are cleaned up based on feedback. Co-authored-by: Valentin Gagarin Co-authored-by: Eelco Dolstra --- .../src/command-ref/nix-collect-garbage.md | 2 +- .../command-ref/nix-env/delete-generations.md | 28 ++++++++++++------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md index a679ceaf7..3cab79f0e 100644 --- a/doc/manual/src/command-ref/nix-collect-garbage.md +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -57,7 +57,7 @@ These options are for deleting old [profiles] prior to deleting unreachable [sto Delete all generations of profiles older than the specified amount (except for the generations that were active at that point in time). *period* is a value such as `30d`, which would mean 30 days. - This is the equivalent of invoking [`nix-env --delete-generations `](@docroot@/command-ref/nix-env/delete-generations.md#generations-days) on each found profile. + This is the equivalent of invoking [`nix-env --delete-generations `](@docroot@/command-ref/nix-env/delete-generations.md#generations-time) on each found profile. See the documentation of that command for additional information about the *period* argument. {{#include ./opt-common.md}} diff --git a/doc/manual/src/command-ref/nix-env/delete-generations.md b/doc/manual/src/command-ref/nix-env/delete-generations.md index d828a5b9e..adc6fc219 100644 --- a/doc/manual/src/command-ref/nix-env/delete-generations.md +++ b/doc/manual/src/command-ref/nix-env/delete-generations.md @@ -20,22 +20,30 @@ This operation deletes the specified generations of the current profile. - The special value `old` - Delete all generations older than the current one. + Delete all generations except the current one. -- `d`:\ - The last *days* days + > **WARNING** + > + > Older *and newer* generations will be deleted by this operation. + > + > One might expect this to just delete older generations than the curent one, but that is only true if the current generation is also the latest. + > Because one can roll back to a previous generation, it is possible to have generations newer than the current one. + > They will also be deleted. + +- `d`:\ + The last *number* days *Example*: `30d` - Delete all generations older than *days* days. - The generation that was active at that point in time is excluded, and will not be deleted. + Delete all generations created more than *number* days ago, except the most recent one of them. + This allows rolling back to generations that were available within the specified period. -- `+`:\ - The last *count* generations up to the present +- `+`:\ + The last *number* generations up to the present *Example*: `+5` - Keep the last *count* generations, along with any newer than current. + Keep the last *number* generations, along with any newer than current. Periodically deleting old generations is important to make garbage collection effective. @@ -61,7 +69,7 @@ $ nix-env --delete-generations 3 4 8 Delete the generations numbered 3, 4, and 8, so long as the current active generation is not any of those. -## Keep most-recent by count count +## Keep most-recent by count (number of generations) ```console $ nix-env --delete-generations +5 @@ -72,7 +80,7 @@ Suppose `30` is the current generation, and we currently have generations number Then this command will delete generations `20` through `25` (`<= 30 - 5`), and keep generations `26` through `31` (`> 30 - 5`). -## Keep most-recent in days +## Keep most-recent by time (number of days) ```console $ nix-env --delete-generations 30d