Skip to content
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.

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

nix-collect-garbage --max-freed is not explained #12132

Open
2 tasks done
Rua opened this issue Jan 2, 2025 · 3 comments
Open
2 tasks done

nix-collect-garbage --max-freed is not explained #12132

Rua opened this issue Jan 2, 2025 · 3 comments

Comments

@Rua
Copy link

Rua commented Jan 2, 2025

Problem

In the online manual and the man page of the nix-collect-garbage command, a --max-freed option is mentioned. But the function of the option is not explained anywhere in the text below. So I don't know what it does.

Proposal

Add it to the documentation.

Checklist


Add 👍 to issues you find important.

@allrealmsoflife
Copy link

I've searched for the --max-freed option and found the following information from the Nix source directory, release notes, and the NixOS Discourse community:


from Nix Source Directory

  1. Release Notes for v0.12 (doc/manual/source/release-notes/rl-0.12.md):
    The --max-freed option was introduced with the following description:

    The garbage collector has a number of new options to allow only some of the garbage to be deleted. The option --max-freed N tells the collector to stop after at least N bytes have been deleted.

  2. Release Notes for v1.7 (doc/manual/source/release-notes/rl-1.7.md):
    The option was enhanced to support unit specifiers:

    The --max-freed option to nix-store --gc now accepts a unit specifier. For example:

    nix-store --gc --max-freed 1G

    This will free up to 1 gigabyte of disk space.


Use Cases from NixOS Discourse

  1. Threshold-based Cleanup:
    The --max-freed option is often used to free just enough space to meet specific thresholds.
    Example:

    nix-collect-garbage --max-freed 10G
  2. System Maintenance:
    Combined with automatic GC to routinely clean up space:

    nix.gc.automatic = true;
    nix.gc.dates = "weekly";
    nix.gc.options = "--max-freed 64G";
  3. Avoiding Store Bloat:
    Useful for developers with ephemeral packages, though the garbage collector may not always prioritize the oldest or largest items.
    Example:

    nix-collect-garbage --max-freed 5G --delete-older-than 30d

Key Points

  • What It Does: The --max-freed option instructs the garbage collector to stop after freeing at least the specified amount of disk space.
  • Unit Specifiers: Supported units include K (kilobytes), M (megabytes), and G (gigabytes) for convenience.

Not sure how to propose a documentation update for this? 😊

@roberth
Copy link
Member

roberth commented Jan 4, 2025

Hi @allrealmsoflife, thank you for researching this!

I see that we do have some documentation here

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

However, that's in nix-store --gc, not nix-collect-garbage.
I think it'd be ok to copy that over, and put a <!-- comment --> about the duplication in both places.
(Not great, but most of the effort is going into the new nix CLI now, so it's not a problem, and the best UX for readers while keeping it simple)

@allrealmsoflife
Copy link

allrealmsoflife commented Jan 7, 2025

Hello! Why is the option though named --max-freed? I understand what it does but I find the wording confusing a bit. The max part tells me almost that it might delete less than max but not more than maximum amount.

Then there is the freed part that is in past participle tense, like how many options are there in this past tense?

When testing it, nix-store --gc --max-freed 1G on my local machine, I expected it to cap the amount of space freed per run, but I noticed that the amount varied: 1024 MB on the first run, 1788 MB on the second, and 942 MB on the third.

Update: Im still failing in building the nix manual, I posted some details in the nix documentation matrix channel.

Update: I built it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants