# Rename a symbol across the repo in Scala with Atlas in 2026

> Atlas provides a robust, terminal-native solution for renaming Scala symbols across an entire repository, ensuring accuracy by integrating with the language server and verifying changes with `sbt

To rename a function, class, or constant across your entire Scala codebase, Atlas leverages a precise, multi-stage workflow that integrates with your existing `sbt` project, `ScalaTest via sbt test` for verification, and `scalafmt` for consistent formatting. This ensures every usage is updated, from compiler-visible calls to documentation, without manual errors.

## Key takeaways

- Atlas uses `lsp` for precise, compiler-aware Scala symbol reference finding.
- Atlas's `grep` tool ensures non-code occurrences like comments and strings are also updated in Scala projects.
- The `edit` tool provides safe, unambiguous mechanical replacements for Scala code.
- Every change is presented as a unified diff for explicit approval before writing to disk.
- Verification with `sbt clean compile` and `sbt test` confirms the integrity of your Scala refactor.

## How Atlas finds all Scala symbol references

Atlas accurately renames Scala symbols by first leveraging the `lsp` tool's `findReferences` operation, ensuring 100% compiler-aware precision. This initial step identifies all true usages of a function, class, or constant within your `sbt` project, avoiding the pitfalls of simple text matching in 2026.

When you initiate a symbol rename in a Scala project, Atlas begins by invoking the `lsp` tool. This tool connects to your Scala language server, which has a deep understanding of your codebase's Abstract Syntax Tree (AST) declarations, including `traits`, `implicits`, and `sbt` modules. Unlike a naive `grep` search, `lsp findReferences` provides an authoritative list of all actual call sites and declarations, distinguishing between a symbol named `User` and a string literal containing "User". This precision is crucial for Scala's rich type system, ensuring that only the intended symbol is targeted for refactoring, preventing unintended modifications that could break your `sbt` build or `ScalaTest` suites. Atlas's indexing capabilities, built on tree-sitter, further enhance this process by providing a robust foundation for semantic understanding.

## Updating non-code occurrences of Scala symbols

Beyond compiler-visible code, Atlas uses `grep` to find additional occurrences of a Scala symbol, such as those in comments or documentation. This crucial second step ensures that even non-code references, like a mention in a `README.md` or a string literal, are updated, providing a complete refactor in 2026.

While the `lsp` tool provides type-system-aware references, a comprehensive Scala symbol rename requires addressing instances outside the compiler's view. Atlas addresses this by running `grep` for the old symbol name. This catches occurrences in places like `src/main/scala/com/example/MyService.scala` comments, `build.sbt` configuration entries, or even markdown documentation files. For example, if you rename `oldFunction` to `newFunction`, `grep` will find `// TODO: Refactor oldFunction` or `val message = "Called oldFunction"`. This two-pronged approach,`lsp` for semantic accuracy and `grep` for textual completeness,ensures that your Scala project's documentation and auxiliary files remain consistent with your refactored code, preventing confusion for future developers.

## Safe mechanical renaming with Atlas's edit tool

Applying the mechanical changes for a Scala symbol rename is handled by Atlas's `edit` tool, which performs `replaceAll` operations with strict safety checks. For instance, if `edit` finds multiple ambiguous matches in a single file for a specific replacement, it will throw an error rather than silently corrupting your code, ensuring 0 unintended changes.

Once Atlas has identified all references and occurrences, the `edit` tool takes over for the mechanical replacement. For each file, `edit` uses `replaceAll` to update the old symbol name to the new one. A key safety feature of `edit` is its refusal to perform ambiguous single replacements. If, for example, you try to rename `User` and `edit` finds `User` and `UserGroup` in the same line without sufficient context to differentiate, it will flag an error. This prevents silent corruption of your Scala code. Atlas computes a unified diff for every file edit, presenting it for your approval before any changes are written to disk. This allows you to review every modification, ensuring the refactor aligns with your expectations for your `src/main/scala` files and `build.sbt` configurations.

## Reviewing and verifying Scala symbol renames

After Atlas proposes changes for a Scala symbol rename, a critical review and verification phase ensures code integrity. Atlas presents a unified diff for every file, allowing you to approve or reject changes before they are written, and then prompts you to run `sbt clean compile` and `sbt test` to confirm 100% functionality.

Atlas's workflow is permission-gated, meaning every tool call and file edit requires your explicit approval. Before writing any changes, Atlas displays a comprehensive unified diff, showing exactly what will change in files like `src/main/scala/com/example/MyClass.scala` or `project/Dependencies.scala`. You can review these proposed edits, ensuring they are correct. Once approved, Atlas applies the changes and then prompts you to verify the refactor. This involves running `bash` commands like `sbt clean compile` to check for compilation errors and `sbt test` to execute your `ScalaTest` suites. Finally, Atlas recommends a final `grep` for the old symbol name to confirm zero remaining hits, providing a robust safety net for your Scala codebase. Atlas can even stage and create commits on your behalf, streamlining the entire refactoring process.

## Steps

1. Run `atlas` in your Scala project directory containing `build.sbt`.
2. Instruct Atlas to rename your desired Scala symbol (e.g., 'rename function oldName to newName').
3. Atlas will use `lsp findReferences` to get authoritative usages from the Scala language server.
4. Atlas will then use `grep` to find non-code occurrences in comments, strings, and documentation.
5. Review the proposed changes presented as a unified diff by Atlas's `edit` tool.
6. Approve the changes for Atlas to apply them to your Scala files.
7. Run `bash sbt clean compile` to ensure the refactored Scala code compiles without errors.
8. Execute `bash sbt test` to run your `ScalaTest` suites and confirm no regressions.
9. Perform a final `bash grep -r 'oldName' .` to verify all instances of the old symbol are gone.

## FAQ

### How does Atlas handle Scala implicits or complex type parameters during a rename?

Atlas leverages the Scala language server via the `lsp` tool, which understands the full context of your codebase, including `implicits`, `traits`, and complex type parameters. This semantic understanding ensures that renames correctly propagate through Scala's advanced type system, unlike simple text-based find-and-replace.

### Can Atlas rename a symbol across multiple `sbt` modules in a large Scala project?

Yes, Atlas is designed to work across multi-module `sbt` projects. By integrating with the language server, Atlas can identify and rename symbols consistently across all `sbt` modules, ensuring a unified refactor throughout your entire Scala repository.

### What if Atlas proposes a change I don't want in my Scala code?

Atlas operates with explicit user approval. Before any changes are written, Atlas presents a unified diff for every file edit. You can review these proposed changes and choose to approve or deny them, giving you full control over the refactoring process in your Scala project.

### How does Atlas ensure my Scala tests still pass after a rename?

After applying the mechanical renames, Atlas prompts you to run your test suite. For Scala projects, this means executing `bash sbt test`, which runs your `ScalaTest` cases. This crucial step verifies that the refactor has not introduced any regressions and that your application's behavior remains correct.

### Does Atlas integrate with `scalafmt` for code style after a rename?

While Atlas focuses on the refactoring itself, it encourages a complete workflow. After a rename, you can easily run `bash scalafmt` to reformat your Scala code according to your project's style guidelines, ensuring consistency alongside the structural changes.

### Is Atlas safe to use with production Scala codebases?

Yes, Atlas is built with safety as a core principle. Its permission-gated tool calls, read-only plan agent, unified diff review, and explicit approval steps minimize risk. For Scala projects, the final verification with `sbt clean compile` and `sbt test` provides a robust safety net before committing changes.

---

Canonical HTML: https://runatlas.sh/resources/stacks/rename-a-symbol-across-the-repo-in-scala
Source of truth: aeo_pages row `/resources/stacks/rename-a-symbol-across-the-repo-in-scala` (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.