Skip to content

move all unique information on garbage collection to nix-store --gc #9208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
fricklerhandwerk wants to merge 8 commits into from
Closed

move all unique information on garbage collection to nix-store --gc #9208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
de3f510
remove superfluous phrase
fricklerhandwerk Oct 23, 2023
43bf51f
move warning into the list item contents
fricklerhandwerk Oct 23, 2023
eec22e7
dedent lists
fricklerhandwerk Oct 23, 2023
1e7d23d
"roots" -> garbage collection roots
fricklerhandwerk Oct 23, 2023
623207b
use imperative in examples
fricklerhandwerk Oct 23, 2023
87ba5e2
add links
fricklerhandwerk Oct 23, 2023
f42bfe7
move all unique information on garbage collection to `nix-store --gc`
fricklerhandwerk Oct 23, 2023
d5e6534
fix broken link
fricklerhandwerk Oct 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions doc/manual/src/SUMMARY.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
13 changes: 6 additions & 7 deletions doc/manual/src/command-ref/nix-collect-garbage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand All @@ -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.

Expand Down
70 changes: 44 additions & 26 deletions doc/manual/src/command-ref/nix-store/gc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,45 +8,63 @@

# 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 “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:

- `--print-roots`\
This operation prints on standard output the set of roots used by
the garbage collector.
- `--print-roots`

- `--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.
This operation prints on standard output the set of roots used by
the garbage collector.

- `--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-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*

The behaviour of the collector is also influenced by the
`keep-outputs` and `keep-derivations` settings in the Nix
configuration file.
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.

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}}
Expand All @@ -55,7 +73,7 @@ number of bytes that would be freed.

# Examples

To delete all unreachable paths, just do:
Delete all unreachable paths:

```console
$ nix-store --gc
Expand All @@ -64,7 +82,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))
Expand Down
73 changes: 0 additions & 73 deletions doc/manual/src/package-management/garbage-collection.md
View file
Open in desktop

@roberth roberth Oct 24, 2023

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would prefer to move everything that isn't CLI here, because nix-store --gc isn't the only way to run GC.
For instance, we have also have nix store gc and the auto-gc options.

@fricklerhandwerk fricklerhandwerk Oct 24, 2023 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In that case we could move it under the new section created in #9206, as that's really about the store. Okay, I'll put it into draft until that's merged.

@Ericson2314 Ericson2314 Oct 25, 2023

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah exactly! Now that we have the store section we can document how GC works in general, and in fact some information that is currently on the man pages can probably move there instead.

This file was deleted.

18 changes: 0 additions & 18 deletions doc/manual/src/package-management/garbage-collector-roots.md
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion doc/manual/src/package-management/profiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down