vvv
vvv renames, moves and rewrites code across a project using syntax, not string matching. It reads declarations, identifiers and imports, so a rename follows every reference and a move rewrites every path that pointed at it. Nothing is written until you have seen the diff, and every write can be undone.
Install
cargo install vvv-rs
Prebuilt binaries for Linux (x86_64, aarch64), macOS (x86_64, aarch64) and
Windows are attached to each release.
The binary is vvv. The default build includes Rust, TypeScript and the picker. To
install a subset, name the features, e.g. --no-default-features --features rust,tui.
Commands
Every command runs against the current directory (-C <dir> picks another) and prints
human output (--json prints the machine-readable result).
Find
vvv search <name> # every identifier spelling the name
vvv search --symbol <kind> # declarations of one kind: function, struct, trait, …
vvv search '<pattern>' # ast-grep structural pattern, e.g. 'fn $N($$$) { $$$ }'
Understand
vvv outline <file> # declarations, visibility, module path
vvv references <name> # every use, judged like a rename
vvv where <name> --from <file> # the declaration, and the import to write there
vvv deps <file> # what the file imports, and who imports it
vvv explain <file>:<line>:<column> # what is at a position
vvv surface <package> # what a package offers, and who takes it
vvv impact <name> # who would feel a change, ring by ring
vvv dead # declarations nothing refers to
vvv imports <file> # unresolved, unused or redundant imports
Change
vvv rename <name> <new> # the declaration and every reference
vvv move <from> <to> # a file or directory, and the paths pointing at it
vvv move --symbol <name> <from> <to> # one declaration between files
vvv rewrite '<pattern>' '<template>' # pattern matches, template expanded
vvv batch <file.json> # several intents as one transaction; - reads stdin
A changing command previews and stops. --apply writes the plan, --diff prints the
full patch of every file, and --select acts on chosen rows only.
After
vvv undo # reverse the newest apply
vvv history # the ledger, oldest first
Interfaces
vvv # the picker, in a terminal
vvv serve # JSON lines in, JSON lines out
How it decides
vvv reads syntax, not types. It knows what a declaration is, what an identifier is, and how modules and imports connect; it does not know which struct a method belongs to.
A changing command judges every candidate and prints it with a verdict:
✓refers to the declaration you named;?cannot be tied to it — a bare name with no import, a method reached through a type, a path whose head cannot be placed;✗refers to a different declaration of the same name.
When several declarations share the name, --in <file> chooses one. --select narrows
the occurrences by the row numbers printed, or by the content ids from --json. Nothing
is dropped quietly.
A preview of a rename reads:
$ vvv rename Language Lang
rename Language → Lang
● trait Language ◆ vvv_core::lang::Language src/lang/mod.rs:64:1
✓ 3 3 files
1 src/lang/mod.rs
1 src/lib.rs
1 src/other.rs
? 1 1 file ∅ unresolved left out
src/other.rs
4 10:5 Language::new()
✗ 0
✓ 3 ? 1 ✗ 0 3 files → 2 occurrences in 2 files
hint: --apply to write · --select 4 for the ? rows alone · -v to list the ✓ rows
The plan records the content of every file it touches, so it refuses to apply to a file
that changed since the preview. Apply is all-or-nothing, and vvv undo reverses the
newest apply.
Output
Every command draws from one set of marks:
| mark | meaning |
|---|---|
● |
a declaration; its module address follows as ◆ |
○ |
a use, not a declaration |
→ ← |
an import / imported by |
↗ |
a re-export |
✓ ? ✗ |
refers to the declaration / can't tell / another one |
± |
a structural edit: a mod line, a visibility |
! |
left to you, with the reason |
◆ |
a module address (crate::a::b) |
∅ |
nothing |
+N |
the match continues for N more lines |
Rows are numbered in the order printed; those numbers are what --select takes.
Options
| flag | meaning |
|---|---|
-C <dir> |
run against this project root |
--json |
print the machine-readable result (protocol) |
--color auto|always|never |
colour policy; NO_COLOR is respected |
-v |
expand what the human view collapses |
--diff |
print a preview's full patch, not only structural edits |
Limits
vvv follows functions, structs, enums, traits, type aliases, constants and modules
through imports, crate::/self::/super:: paths, Cargo workspaces, pub use /
export … from re-exports, and relative TypeScript imports including index files.
What it cannot place is reported, not skipped.
Not handled: tsconfig path aliases, #[path] modules, code inside macro bodies, and
glob imports of a module whose symbol moves. A change vvv cannot make becomes a ! row
with the text it would have written. Method and field renames match by name and are
narrowed by selection, because syntax alone does not say which type they belong to.
JSON and sessions
--json prints one documented document per command, errors included, each with a stable
code and a hint. vvv serve reads the same commands as JSON lines on stdin and
answers on stdout, keeping the tree between requests. The contract is in
docs/protocol.md.
Documentation
- docs/guide.md — every command in detail, and the full mark legend.
- docs/protocol.md — the JSON contract.
- docs/architecture.md — the crates and their rules.
- CHANGELOG.md — what changed in each release.
- CONTRIBUTING.md — build, test and send a change.