Atlas migrates a deprecated C++ API across every callsite by front-loading enumeration, because this is the workflow that punishes half-measures. The lsp tool's findReferences operation yields the complete caller set from the language server, across every header and translation unit in the CMakeLists.txt build. todowrite turns that set into tracked work so a partially migrated codebase cannot be mistaken for a finished one. Each callsite is then migrated with apply_patch, which seeks the hunk's context and old_lines and throws Failed to find expected lines rather than misapplying to a drifted file. GoogleTest via ctest proves each file after it changes.
How do I find every C++ callsite of a deprecated function?
Enumerate every caller with the lsp tool's findReferences operation on the deprecated symbol, then cross-check with grep for dynamic or string-based usages. In a C++ project with a CMakeLists.txt, findReferences reaches across headers and translation units in 2026, which a header-only grep would miss.
C++ makes enumeration harder than most languages. A deprecated function can be called from a .cpp, referenced in a .h, invoked through a macro, or bound into a template that only instantiates in one translation unit. The lsp tool asks the language server for the real reference set, which resolves overloads and template instantiations. grep then catches what the symbol graph cannot see: usages assembled by preprocessor macros or referenced by name in a string. Both are needed, and Atlas runs both.
Why does Atlas create a todowrite entry per C++ callsite?
Atlas creates one todowrite entry per callsite so partial progress is visible and nothing is silently skipped. A C++ migration touching 40 translation units across several CMake targets cannot be held in a single session's head in 2026, and an untracked callsite is exactly the one that ships broken.
The todowrite list is the ledger. Each entry names a real C++ file, for example src/net/socket.cpp or include/net/socket.h, and is marked complete only after that file's tests pass. That means a migration interrupted halfway is legible: you can see which translation units are done and which are not. Without the list, a large C++ migration degrades into a guess about coverage, and the deprecated symbol survives in a corner of the build nobody compiled that day.
How does apply_patch avoid breaking a drifted C++ file?
Atlas migrates each C++ callsite with apply_patch, which seeks the hunk's context and old_lines and throws Failed to find expected lines rather than guessing. If src/net/socket.cpp changed since Atlas read it in 2026, the patch fails loudly instead of landing in the wrong place.
Blind application is how a mechanical C++ migration corrupts a file. apply_patch anchors on surrounding context lines, so it can only apply where the code still matches what Atlas saw. A drifted header, a rebase that moved a function, a concurrent edit by a teammate: any of these produce Failed to find expected lines, which is a recoverable error. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so you review the change to each translation unit before it exists on disk.
How do I verify each C++ file after migrating its callsites?
Run the affected tests with GoogleTest via ctest after each file, and mark the todo completed only once they pass. A C++ build in 2026 can compile cleanly and still fail at runtime, so a green compile of the CMake target is necessary but not sufficient evidence.
Verification per file, not per migration, is what localizes a break. After apply_patch lands in src/net/socket.cpp, Atlas runs GoogleTest via ctest through the bash tool, which records the process exit code in its metadata alongside the output. If the suite goes red, exactly one file changed, so the cause is unambiguous. Only then does the todowrite entry flip to completed. Any new dependency the replacement API needs is added through vcpkg and declared in CMakeLists.txt.
How do I prove no C++ callsite was missed?
Finish by grepping for the deprecated symbol and confirming zero remaining hits, then delete the old implementation. A C++ migration is only complete when the deprecated function no longer exists, because in 2026 any surviving declaration in a header is an invitation for a new caller next week.
The final grep is the proof. Zero hits across every .cpp and .h in the repository means the enumeration was complete and every todowrite entry was honestly closed. Deleting the old implementation makes the migration irreversible in the right way: the compiler now enforces what the todo list only tracked. Run clang-format on the touched files so the diff carries the API change rather than brace style, and run the full GoogleTest via ctest suite one last time.
How does Atlas keep a large C++ migration reviewable?
Atlas keeps a C++ migration reviewable through three mechanisms: a unified diff surfaced for approval before every write, one apply_patch per file, and git patch snapshots for rollback. In 2026 that means a 40 file migration is 40 reviewable units, not one uninspectable commit.
Reviewability is a function of granularity. Because Atlas patches one C++ file at a time and shows the unified diff before writing, each translation unit is approved on its own. Atlas snapshots file changes as git patches, so a single bad migration to include/net/socket.h can be diffed and rolled back without unwinding the other 39. Atlas also reads git branches, status, and diffs and can stage and create commits on your behalf, so the migration lands as a series of legible commits.
Step by step
- 01Run atlas in your C++ project, the one with a CMakeLists.txt, and let Atlas read your headers, translation units, and build targets.
- 02Enumerate every caller with the lsp tool's findReferences operation on the deprecated symbol, and cross-check with grep for dynamic or macro-assembled usages.
- 03Create one todowrite entry per callsite, naming the real .cpp or .h file, so partial progress is visible and nothing is silently skipped.
- 04Migrate each callsite with apply_patch; it seeks the hunk's context and old_lines and throws Failed to find expected lines rather than guessing at a drifted file.
- 05Review the unified diff Atlas surfaces for each translation unit before it is written.
- 06Add any dependency the replacement API needs through vcpkg and declare it in CMakeLists.txt.
- 07Run the affected tests with GoogleTest via ctest after each file, and mark the todo completed only once they pass.
- 08Finish by grepping for the deprecated symbol, confirming zero remaining hits, deleting the old implementation, and running clang-format.
Frequently asked questions
- how to migrate every callsite of a deprecated c++ function
- Enumerate the callers with Atlas's lsp tool findReferences operation, cross-check with grep for macro usages, create one todowrite entry per callsite, then migrate each with apply_patch and verify with GoogleTest via ctest before closing the todo.
- does findReferences work across c++ headers and translation units
- Yes. The lsp tool asks the language server, which resolves overloads and template instantiations across your CMakeLists.txt build. Cross-check with grep for dynamic or string-based usages that the symbol graph cannot see.
- atlas Failed to find expected lines error what does it mean
- apply_patch seeks the hunk's context and old_lines and throws Failed to find expected lines when the file has drifted since Atlas read it. That is a safety feature: the patch refuses to misapply to your .cpp rather than guessing.
- how do i track progress on a large c++ api migration
- Create one todowrite entry per callsite, naming the real .cpp or .h file. Mark each complete only after GoogleTest via ctest passes for that file, so a partially migrated codebase cannot be mistaken for a finished one.
- how do i know i did not miss a c++ caller
- Finish by grepping for the deprecated symbol and confirming zero remaining hits, then delete the old implementation so the compiler enforces completeness. Run the full GoogleTest via ctest suite and clang-format on the touched files.
- can atlas add a vcpkg dependency during a migration
- Yes. Atlas can add the replacement API's dependency through vcpkg and declare it in CMakeLists.txt. Every tool call is permission-gated against allow, ask, and deny rules before it runs, so you can set that step to ask.
- how do i review a 40 file c++ migration from an ai agent
- Atlas patches one file at a time and computes a unified diff for every file edit, surfacing it for approval before writing. Atlas also snapshots file changes as git patches, so a single bad translation unit can be rolled back without unwinding the rest.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Migrate a Deprecated API Across Every Callsite with Atlas (2026 Workflow)
How to migrate a deprecated API across every callsite with Atlas in 2026: the lsp tool's findReferences enumerates callers, todowrite tracks them, apply_patch migrates each one.
Atlas for C++ in 2026
In 2026, C++ developers adopt Atlas, the terminal-native AI coding agent, to enhance productivity. Atlas offers secure, context-aware assistance for modern C++ projects, integrating with CMake and ensuring code quality
Write unit tests for untested code in C++ with Atlas (2026)
Add GoogleTest coverage to an untested C++ module with Atlas in 2026: enumerate symbols with lsp, copy the repo's conventions, and actually run ctest on the result.
Refactor a Legacy Module in C++ with Atlas (2026)
How to refactor a legacy C++ module with Atlas in 2026: enumerate callsites with the lsp tool, restructure with apply_patch, and prove behavior with GoogleTest via ctest.
Add a regression test for a bug fix in C++ with Atlas (2026)
Red first, then green. Atlas proves a C++ bug with a failing GoogleTest case, applies the fix with edit, and re-runs ctest so the exit code makes the result unambiguous.
Document a C++ Module with a README using Atlas in 2026
In 2026, Atlas helps C++ developers document modules with accurate READMEs. It uses lsp, grep, and bash to describe what your C++ code actually does today, integrating with CMake, vcpkg, and GoogleTest via ctest.
Plan a Multi-File Change Before Editing in C++ with Atlas (2026)
Design a C++ change across headers and translation units in 2026 before one line moves: Atlas plan mode denies every edit tool until you approve the plan and switch to build.
Upgrade a C++ Dependency and Fix Breakage with Atlas in 2026
In 2026, C++ developers use Atlas to efficiently upgrade major dependencies with vcpkg, automatically fixing compile and GoogleTest failures. Atlas streamlines the entire migration process.