libra update-index
Command reference for `libra update-index`
Modify the index directly — a focused subset of git update-index. The
companion to write-tree: --cacheinfo registers an index
entry from an object id without reading the working tree, so an index can be
built purely from objects.
Synopsis
libra update-index --add <path>...
libra update-index --remove <path>...
libra update-index --cacheinfo <mode>,<object>,<path>...
Description
update-index applies, in order: every --cacheinfo entry, then the positional
paths (removed with --remove, otherwise (re)staged from the working tree), and
saves the index.
--cacheinfo <mode>,<object>,<path>inserts/updates an entry directly. The object need not exist yet (matching Git), so you can build an index from hashes computed withhash-object.<mode>is an octal file mode:100644(file),100755(executable),120000(symlink),160000(gitlink). The object id length must match the repository hash format. The path is an index key — absolute paths and..traversal are rejected.--add <path>...(re)stages files from the working tree, allowing paths not yet tracked. Without--add, a positional path must already be tracked.--remove <path>...drops the named paths from the index.
--force-remove (Libra 0.23.21, plan issues/490 SW-02) drops the positional paths from the index regardless of whether the working-tree file exists; paths the index does not know are a no-op, every stage of an unmerged path is removed, and it wins over --add/--remove.
--skip-worktree / --no-skip-worktree (Libra 0.23.30, plan issues/490 SW-07) set/clear the skip-worktree bit on tracked paths (index v3 extended flags): status/diff then ignore the working-tree copy and no command restages it. The mark is index-only — the working tree is never read. A path that is not in the index fails with Unable to mark file (exit 128). Marking rewrites the index as format v3; clearing returns it to v2 once no entry carries extended flags.
Options
| Option | Description | Example |
|---|---|---|
--add |
Allow positional paths to add new (untracked) files. | libra update-index --add a.txt |
--remove |
Remove the positional paths from the index. | libra update-index --remove old.txt |
--cacheinfo <mode>,<object>,<path> |
Register an entry from an object id (repeatable). | libra update-index --cacheinfo 100644,<oid>,dir/f.txt |
--json / --machine |
Structured output: { updated: <n>, removed: <n> }. |
libra --json update-index --add a.txt |
--skip-worktree |
Mark tracked paths with the skip-worktree bit (index v3): status/diff ignore the working-tree copy and it is never restaged. Untracked paths fail with exit 128. | libra update-index --skip-worktree s.txt |
--no-skip-worktree |
Clear the skip-worktree bit again; the index returns to v2 when no extended flags remain. | libra update-index --no-skip-worktree s.txt |
Exit codes
| Code | Meaning |
|---|---|
0 |
The index was updated and saved. |
128 |
Not inside a repository, a usage error (bad --cacheinfo, untracked path without --add), a missing working-tree file, or --skip-worktree/--no-skip-worktree on a path that is not in the index. |
Examples
# Build an index entry from an object id, then write the tree
OID=$(libra hash-object -w data.bin)
libra update-index --cacheinfo 100644,"$OID",assets/data.bin
libra write-tree
# Stage and unstage working-tree files
libra update-index --add src/new.rs
libra update-index --remove src/old.rs
# Mark a path index-only: status/diff ignore its working-tree copy
libra update-index --skip-worktree s.txt
libra ls-files -v # `S s.txt`
libra update-index --no-skip-worktree s.txt
Comparison with Git
| Task | Libra | Git |
|---|---|---|
| Stage a file | libra update-index --add f |
git update-index --add f |
| Remove a path | libra update-index --remove f |
git update-index --remove f |
| Mark a path skip-worktree | libra update-index --skip-worktree f |
git update-index --skip-worktree f |
| Register by id | libra update-index --cacheinfo m,oid,p |
git update-index --cacheinfo m,oid,p |
Deferred (not exposed): bare-path stat refresh, --chmod,
--assume-unchanged, --index-info, and other Git flags.
Index v3 and downgrade note
Before downgrading to a Libra release whose index reader rejects v3 (0.23.x and earlier), clear the marks so the index returns to v2:
libra ls-files -v | grep '^S ' | cut -d' ' -f2- |
xargs -r libra update-index --no-skip-worktree