rxp_gc: Garbage Collect Rixpress Build Artifacts and Logs

In rixpress: Build Reproducible Analytical Pipelines with 'Nix'

Garbage Collect Rixpress Build Artifacts and Logs

Description

This function performs garbage collection on Nix store paths and build log files generated by rixpress. It can operate in two modes: full garbage collection (when keep_since = NULL) or targeted deletion based on log file age.

Usage

rxp_gc(
  keep_since = NULL,
  project_path = ".",
  dry_run = FALSE,
  timeout_sec = 300,
  verbose = FALSE,
  ask = TRUE
)

Arguments

keep_since	Date or character string (YYYY-MM-DD format). If provided, only build logs older than this date will be targeted for deletion, along with their associated Nix store paths. If NULL, performs a full Nix garbage collection. Default is NULL.
project_path	Character string specifying the path to the project directory containing the _rixpress folder with build logs. Default is "." (current directory).
dry_run	Logical. If TRUE, shows what would be deleted without actually performing any deletions. Useful for previewing the cleanup operation. Default is FALSE.
timeout_sec	Numeric. Timeout in seconds for individual Nix commands. Also used for concurrency lock expiration. Default is 300 seconds.
verbose	Logical. If TRUE, provides detailed output including full paths, command outputs, and diagnostic information about references preventing deletion. Default is FALSE.
ask	Logical. If TRUE, ask for user confirmation before performing deleting artifacts. Default is TRUE.

Details

The function operates in two modes:

Full Garbage Collection Mode (keep_since = NULL):

• Runs nix-store --gc to delete all unreferenced store paths

• Does not delete any build log files

• Suitable for complete cleanup of unused Nix store paths

Targeted Deletion Mode (keep_since specified):

• Identifies build logs older than the specified date

• Extracts store paths from old logs using rxp_inspect()

• Protects recent store paths by creating temporary GC roots

• Attempts to delete old store paths individually using nix-store --delete

• Deletes the corresponding build log .json files from _rixpress/

• Handles referenced paths gracefully (paths that cannot be deleted due to dependencies)

Concurrency Safety: The function uses a lock file mechanism to prevent multiple instances from running simultaneously, which could interfere with each other's GC root management.

Reference Handling: Some store paths may not be deletable because they are still referenced by:

• User or system profile generations

• Active Nix shell environments

• Result symlinks in project directories

• Other store paths that depend on them

These paths are reported but not considered errors.

Value

Invisibly returns a list with cleanup summary information:

• kept: Vector of build log filenames that were kept

• deleted: Vector of build log filenames targeted for deletion

• protected: Number of store paths protected via GC roots (date-based mode)

• deleted_count: Number of store paths successfully deleted

• failed_count: Number of store paths that failed to delete

• referenced_count: Number of store paths skipped due to references

• log_files_deleted: Number of build log files successfully deleted

• log_files_failed: Number of build log files that failed to delete

• dry_run_details: List of detailed information when dry_run = TRUE

See Also

rxp_list_logs, rxp_inspect

Other utilities: print.rxp_derivation(), rxp_check_chronicles(), rxp_copy(), rxp_init(), rxp_inspect(), rxp_list_logs(), rxp_load(), rxp_read(), rxp_trace()

Examples

## Not run: 
# Preview what would be deleted (dry run)
rxp_gc(keep_since = "2025-08-01", dry_run = TRUE, verbose = TRUE)

# Delete artifacts from builds older than August 1st, 2025
rxp_gc(keep_since = "2025-08-01")

# Full garbage collection of all unreferenced store paths
rxp_gc()

# Clean up artifacts older than 30 days ago
rxp_gc(keep_since = Sys.Date() - 30)

## End(Not run)

rixpress documentation built on Feb. 19, 2026, 9:06 a.m.