libra gc

Historical design for pruning unreachable loose objects and cleaning stale pack sidecar files.

Status: unpublished. libra gc is not registered in the public CLI in the current release. Running it returns the standard unknown-command error (LBR-CLI-001). Use libra maintenance run --dry-run --task gc for the currently published maintenance entry point. The notes below describe preserved design material, not a user-visible gc command contract.

Synopsis

libra gc [--dry-run] [--prune=<date> | --no-prune] [--aggressive] [--auto] [--force]

Description

The unpublished design first expires reflogs using the default gc.reflogExpire and gc.reflogExpireUnreachable policy, then traces objects reachable from repository references, remaining reflogs, the index, in-progress operation state, and local AI catalogs. It prunes unreachable loose objects that match the configured prune cutoff. When cloud backup is configured, unsynced object_index rows retain matching loose objects as pending backup data; they are reported as retained unreachable objects rather than counted as reachable graph roots. It also inspects .libra/objects/pack/ and removes stale sidecar files such as orphan .idx files when they are old enough and not protected by a matching .keep file.

Valid .pack + .idx pairs are verified through Libra's existing verify-pack/pack decoding path. Malformed pack groups are retained and reported instead of blocking unrelated cleanup. If reachable-object traversal is incomplete, non-dry-run loose-object pruning is skipped for that invocation and the reason is emitted in warnings[]. Libra currently does not rewrite valid packs, perform delta compression, create cruft packs, or repack loose reachable objects.

Options

Examples

libra gc
libra gc --dry-run --prune=now
libra gc --prune=now
libra gc --prune=never --json

Human Output

Human mode prints a loose-object summary and pack-directory statistics:

Enumerating loose objects: 3 scanned, 2 reachable, 1 unreachable.
Expired 1 reflog entry across 2 ref(s).
Pruned 1 loose object(s).
Checked 1 pack(s), containing 42 indexed object(s).
Cleaned 0 stale pack file(s).

--dry-run switches deletion lines to Would prune / Would clean. --quiet suppresses stdout while preserving errors and warnings on stderr.

Structured Output

If this command is published in a future release, --json should return a gc envelope containing:

• loose_objects.scanned, reachable, unreachable, pruned, and retained
• reflogs.refs_scanned, entries_scanned, pruned, and rewritten
• reachable_objects
• unreachable_objects[] with object id, type, action, and reason
• pack_files.packs_verified, objects_in_packs, and stale_files[]
• warnings[] for accepted compatibility flags, stale roots, incomplete traversal, and forced locks

{
  "ok": true,
  "command": "gc",
  "data": {
    "prune": "now",
    "dry_run": false,
    "loose_objects": {
      "scanned": 3,
      "reachable": 2,
      "unreachable": 1,
      "pruned": 1,
      "retained": 0
    },
    "reflogs": {
      "refs_scanned": 2,
      "entries_scanned": 12,
      "pruned": 1,
      "rewritten": 0
    },
    "reachable_objects": 2,
    "unreachable_objects": [
      {
        "oid": "0123456789abcdef0123456789abcdef01234567",
        "object_type": "blob",
        "action": "pruned",
        "reason": "unreachable loose object matched prune policy"
      }
    ],
    "pack_files": {
      "directory_exists": true,
      "packs_verified": 1,
      "objects_in_packs": 42,
      "stale_files": []
    },
    "warnings": []
  }
}

Compatibility

The unpublished design aligns with Git's core safety rule: reachable objects are retained, and unreachable loose objects are pruned only when the prune policy allows it. Before pruning objects, Libra runs the same default policy as libra reflog expire --all without --rewrite, --updateref, or --stale-fix. The implementation is intentionally narrower than git gc: it does not perform full repacking, bitmap generation, commit-graph maintenance, or cruft-pack creation.

.libra/gc.lock serializes concurrent libra gc runs. It is not a repository-wide write lock: commands that write new objects or update refs do not currently acquire this lock, so --prune=now should be used when no other writer is active. --force only replaces a stale lock when Libra can verify that the recorded PID is no longer running.

Error Handling