LibraLibra
LibraLibra
DocsBlogLibra
Getting Started
Architecture
Design
Commands
libra addlibra agentlibra alternateslibra applylibra archivelibra authlibra automationlibra bisectlibra blamelibra branchlibra bundlelibra cachelibra cat-filelibra check-attrlibra check-ignorelibra check-mailmaplibra checkoutlibra cherry-picklibra cleanlibra clonelibra cloudlibra code-controllibra codelibra commit-treelibra commitlibra completionslibra configlibra credentiallibra depslibra describelibra diff-fileslibra diff-indexlibra diff-treelibra difflibra dirtylibra fast-exportlibra fast-importlibra fetchlibra filelibra for-each-reflibra format-patchlibra fscklibra gclibra graphlibra greplibra hash-objectlibra hookslibra hydratelibra index-packlibra initlibra investigatelibra layerlibra lfslibra loglibra logfilelibra loginlibra logoutlibra ls-fileslibra ls-remotelibra ls-treelibra maintenancelibra medialibra merge-baselibra merge-filelibra mergelibra metadatalibra mvlibra noteslibra oplibra openlibra pack-objectslibra packagelibra prunelibra publishlibra pulllibra pushlibra read-treelibra rebaselibra refloglibra remotelibra repacklibra replacelibra rererelibra resetlibra restorelibra rev-listlibra rev-parselibra revertlibra reviewlibra revisionlibra rmlibra sandboxlibra servicelibra shortloglibra show-reflibra showlibra sparse-viewlibra stashlibra statslibra statuslibra switchlibra symbolic-reflibra taglibra update-indexlibra update-reflibra usagelibra verify-packlibra whoamilibra worktreelibra write-tree
API Reference
Policy
Commands

libra dirty

Command reference for `libra dirty`

Advisory dirty-set marks (a Libra extension, lore.md §1.1). Git has no equivalent; the cache accelerates status for agents and tooling.

Synopsis

libra dirty <paths>...
libra dirty --list

Description

libra dirty <paths> marks paths dirty in the working_dirty SQLite cache — no file contents are read and the index is never touched. Marks are advisory and can only make the cached view over-report (the safe direction). Nonexistent paths are legal: a deletion IS dirty. Paths must stay inside the repository (an escaping path fails the whole invocation, exit 129).

The cache lifecycle:

  • libra status --scan — the only authoritative rebuild: runs the normal full status and atomically replaces the snapshot (unstaged dirty set + the staged set), stamped with the index fingerprint and HEAD.
  • libra status --cached — consumes the snapshot instead of walking the worktree. Any freshness doubt (index or HEAD changed since the scan; no scan yet) degrades to the full status with a hint — the cache never lies. Snapshot semantics: worktree-only edits made after the scan don't change the index and are invisible to --cached until a rescan or a libra dirty mark records them — that is what the marks are for.
  • libra status --check-dirty — re-verifies only the cached set (O(dirty paths)): rows re-verified clean are pruned; nothing new is found.
  • libra dirty --list — shows the cached rows (kind, source, path) and the cache's freshness.

Default libra status never reads or writes the cache.

Exit codes

CodeMeaning
0Success.
128Not a repository.
129Usage errors (escaping paths, missing arguments).

Examples

libra status --scan               # build the snapshot
libra dirty src/main.rs           # record an edit without a rescan
libra status --cached             # O(dirty) status from the cache
libra status --check-dirty        # prune stale marks
libra --json dirty --list         # structured cache inspection

Comparison with Git

Git has no dirty-set cache surface (its closest machinery is the index stat cache and fsmonitor, both internal). libra dirty and the status --scan/--cached/--check-dirty flags are classified intentionally-different in COMPATIBILITY.md. Note status --cached is unrelated to Git's --cached (= the index).

libra diff

Command reference for `libra diff`

libra fast-export

Command reference for `libra fast-export`

On this page

SynopsisDescriptionExit codesExamplesComparison with Git