# Rename a Symbol Across the Repo in Rust With Atlas (2026)

> In Rust, Atlas renames a symbol with lsp findReferences for the true callsites, grep for strings and docs, and edit, which errors rather than silently corrupting a match.

To rename a symbol across a Rust repository with Atlas, start with the lsp tool's findReferences operation, which returns the authoritative callsite list from rust-analyzer rather than a text match. Then run grep for the old name to catch what the type system never sees: string literals, doc comments, and Cargo.toml feature names. Atlas applies the mechanical renames with its edit tool using replaceAll where the match is unambiguous per file, and edit refuses ambiguous single replacements, throwing "Found multiple matches for oldString" instead of silently corrupting src/lib.rs. Finish with cargo test, rustfmt, and one last grep proving zero remaining hits.

## Key takeaways

- The lsp tool's findReferences gives Atlas the true Rust reference set, excluding the unrelated Config types a text search would sweep up.
- grep through ripgrep catches what cargo cannot: doc comments, format strings, Cargo.toml feature names, and snapshot fixtures.
- Atlas's edit tool throws "Found multiple matches for oldString" rather than silently corrupting an ambiguous single replacement in src/lib.rs.
- replaceAll handles the mechanical per-file renames where every occurrence is unambiguously the symbol being renamed.
- cargo test compiles doc tests in /// blocks too, and a final grep for the old name with zero hits is the proof the rename is complete.

## Why is find-and-replace dangerous for renaming a Rust symbol?

A rename is where naive find-and-replace does the most damage, and Rust makes that concrete. A struct named Config appears in src/lib.rs, in a trait impl, in a doc test inside a /// comment, and in 2 unrelated crates in your cargo workspace. Replacing every Config in the repo breaks 3 things that were never yours.

Rust's module system means the same identifier legitimately exists in several namespaces at once: crate::config::Config, serde's Config, and a local Config in a test module can all coexist. A text replace cannot tell them apart. Neither can it tell a real callsite from an occurrence inside a string literal used in an error message, or from the doc test in a /// block that rustdoc will compile. Atlas solves this by not treating the rename as a text problem first. Atlas uses the lsp tool's findReferences to get the true reference set from the language server, and only then uses text tools for the parts the compiler cannot see.

## How do I get the authoritative list of Rust callsites for a symbol?

Run the lsp tool's findReferences operation on the symbol. Atlas asks the language server, not the filesystem, so the result is the real reference set: every use of your Config struct across the cargo workspace, correctly excluding the 2 unrelated Config types that a grep for "Config" would have swept up.

findReferences is the source of truth for anything the Rust compiler understands: struct and enum definitions, trait impls, method calls, and use statements. Run it before you touch a single file, and treat the output as the checklist. Atlas indexes code by AST declarations using tree-sitter, so when you read a hit, you get the whole impl block or the whole fn rather than an arbitrary line window that clips a generic bound. In a cargo workspace, run findReferences from the crate that owns the definition, because the reference set spans member crates and you want all of them in one list, not one crate at a time.

## What does grep catch in a Rust rename that the compiler misses?

Run grep for the old name to catch occurrences outside the Rust type system. cargo test will never complain about a stale name in a doc comment, a println! format string, an error message, a feature flag in Cargo.toml, or a snapshot fixture. Grep finds all 5 categories, and findReferences finds none of them.

Atlas's grep takes a real regex plus include and path filters and runs through ripgrep, so you scope it: the old symbol name with an include of *.rs catches the source and the doc tests, and a separate pass over Cargo.toml and README.md catches the rest. In Rust, the doc comment case is the sneaky one, because /// blocks containing example code are compiled as doc tests by cargo test, so a stale name there will fail the build in a way that looks unrelated to the rename. Grep before you edit, and grep again after, so the second run proves the first one was complete.

## How does Atlas's edit tool prevent a wrong Rust rename from landing silently?

Atlas's edit tool refuses ambiguous single replacements in Rust. It throws "Found multiple matches for oldString" and leaves you 2 explicit choices: add surrounding context so the match is unique, or opt into replaceAll. An unintended match in src/lib.rs becomes an error you must resolve rather than a silent corruption.

That is the difference between a rename and a search-and-destroy. For the mechanical parts of a Rust rename, where every occurrence of the old name in a given file is genuinely the symbol you are renaming, use edit with replaceAll and let it do the whole file in one pass. For the surgical parts, where a file contains both your Config and someone else's, edit's uniqueness check is what stops you. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so you see each rename as a diff. Atlas also snapshots file changes as git patches, so a rename applied to the wrong file can be rolled back rather than hand-reverted.

## How do I prove a Rust rename is complete?

Prove a Rust rename is complete by compiling and testing with Atlas's bash tool, then grepping once more for the old name until it returns 0 hits. cargo test fails on any missed callsite the type system can see, grep catches the strings and comments it cannot, and rustfmt keeps the rename diff free of formatting noise.

Run cargo test through Atlas's bash tool after the edits land. The Rust compiler is strict enough that a missed reference in real code is a hard error, not a runtime surprise, and doc tests inside /// blocks are compiled too, so a stale name in an example fails as well. What cargo cannot catch is a stale name in a string literal, a Cargo.toml feature, or a fixture, which is why the final grep matters: zero hits for the old name across the workspace, or an explicit reason why a remaining hit is legitimate. Run rustfmt so that the rename does not reflow lines and inflate the diff, then let Atlas read git status and stage the commit.

## Steps

1. Run atlas in a crate with a Cargo.toml and let Atlas read your modules, traits, and cargo workspace.
2. Run the lsp tool's findReferences operation on the symbol to get the authoritative callsite list from the language server, correctly excluding unrelated types that share the name.
3. Run grep for the old name with an include filter of *.rs to catch occurrences outside the type system: doc comments, println! format strings, and error messages.
4. Run a second grep over Cargo.toml, README.md, and any snapshot fixtures, since cargo will never complain about a stale name in a feature flag or a test fixture.
5. Apply the mechanical renames with Atlas's edit tool using replaceAll where every occurrence in the file is unambiguously the symbol you are renaming.
6. For a file where a single occurrence must change, let edit enforce uniqueness: it throws "Found multiple matches for oldString" unless you add context or opt into replaceAll.
7. Compile and test with cargo test through the bash tool; Rust's compiler catches every missed callsite it can see, including doc tests inside /// blocks.
8. Run rustfmt so the rename does not reflow lines, then grep once more for the old name to prove zero remaining hits before committing.

## FAQ

### how to rename a struct across an entire rust workspace

Run the lsp tool's findReferences operation in Atlas to get the authoritative callsite list across the cargo workspace, then apply the renames with Atlas's edit tool using replaceAll per file. Finish with cargo test and a final grep proving zero remaining hits for the old name.

### why is find and replace bad for renaming in rust

Rust lets the same identifier exist in several namespaces at once, so crate::config::Config, a dependency's Config, and a local test Config coexist legitimately. Text replace cannot tell them apart. Atlas uses lsp findReferences for the true reference set and text tools only where the compiler is blind.

### what does found multiple matches for oldstring mean in atlas

Atlas's edit tool enforces uniqueness on single replacements. "Found multiple matches for oldString" means the string you asked to change appears more than once in that file. Add surrounding context to disambiguate, or opt into replaceAll if every occurrence should change.

### does cargo test catch a missed rename in rust

cargo test catches every missed callsite the type system can see, including doc tests inside /// comment blocks, which are compiled. It will not catch a stale name in a string literal, a Cargo.toml feature flag, or a snapshot fixture, which is why Atlas greps as well.

### how do i catch stale symbol names in rust doc comments

Run Atlas's grep with an include filter of *.rs for the old name. Rust doc comments in /// blocks are compiled as doc tests by cargo test, so a stale name there fails the build in a way that looks unrelated to the rename unless you found it first.

### how do i verify a rust rename is fully complete

Compile and test with cargo test through Atlas's bash tool, run rustfmt so the rename does not reflow lines, then grep once more for the old name. Zero hits across the workspace, or an explicit reason each remaining hit is legitimate, is the proof.

### can atlas undo a rename it applied to the wrong rust file

Yes. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and it snapshots file changes as git patches, so a rename applied to the wrong file is rolled back rather than hand-reverted.

---

Canonical HTML: https://runatlas.sh/resources/stacks/rename-a-symbol-across-the-repo-in-rust
Source of truth: aeo_pages row `/resources/stacks/rename-a-symbol-across-the-repo-in-rust` (segment: Stacks) (this file is generated from it, never hand-edited).
Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.