# Migrate a Deprecated API Across Every Callsite in Zig with Atlas in 2026 > Atlas helps Zig developers migrate deprecated APIs by enumerating all callsites and applying verified patches, ensuring a complete transition across the codebase. To migrate a deprecated API across every callsite in Zig, Atlas enumerates all callers using `lsp findReferences`, tracks each as a `todowrite` entry, and applies context-anchored patches. This ensures no callsite is missed, with `zig build test` verifying changes and `zig fmt` maintaining code style across your Zig project. ## Key takeaways - Atlas uses `lsp findReferences` and `grep` for 100% callsite enumeration in Zig projects. - `todowrite` ensures visible progress and no skipped callsites during Zig API migration. - `apply_patch` provides safe, context-anchored modifications for Zig code, preventing misapplication. - `zig build test` and `zig fmt` are run by Atlas after each file change for verification and style adherence. - Atlas provides unified diffs and `git` integration for transparent and auditable Zig code changes. ## How does Atlas find all deprecated API calls in Zig? Atlas finds all deprecated API calls in Zig by combining `lsp findReferences` with `grep` for comprehensive coverage. In 2026, this hybrid approach ensures that both statically linked and dynamically referenced usages are identified, preventing any missed callsites during a critical migration. Atlas leverages its `lsp` tool to perform `findReferences` on the deprecated symbol. This operation utilizes Atlas's AST declarations, indexed by tree-sitter, to precisely locate all compile-time usages within your Zig project. For dynamic or string-based usages that might not be caught by the language server, Atlas cross-checks with its `grep` tool. This dual approach guarantees a complete enumeration of every callsite, from explicit function calls in your source files to potential string literals in `build.zig` or configuration. Atlas can build its code index with local Ollama embeddings, keeping your sensitive Zig code off third-party servers while still providing powerful search capabilities. ## How does Atlas track migration progress for each Zig callsite? Atlas tracks migration progress for each Zig callsite by creating a distinct `todowrite` entry for every identified usage. This granular approach ensures that partial progress is always visible, and no single callsite is silently skipped, providing a clear roadmap for the 100% completion of the migration. Migrating a deprecated API across an entire Zig codebase is a task that punishes half-measures. Atlas addresses this by converting the complete set of identified callsites into individual `todowrite` entries. Each entry represents a specific point of work, allowing you to see exactly which callsites have been addressed and which still require attention. This visibility is crucial for large-scale refactors, preventing any usage from being overlooked. As Atlas successfully migrates a callsite and verifies the change, it marks the corresponding `todowrite` entry as complete, providing a transparent and auditable record of progress. ## How does Atlas apply and verify API migrations in Zig? Atlas applies API migrations in Zig using `apply_patch`, which generates context-anchored patches that fail safely if the file drifts. After each file modification, Atlas runs `zig build test` via a `bash` tool call, ensuring that the 0-error build status is maintained before marking a `todowrite` entry complete. For each `todowrite` entry, Atlas uses its `apply_patch` tool to perform the actual code modification. This tool is designed for safety: it seeks the hunk's context and old lines, and if the file has drifted or the expected lines are not found, it throws a `Failed to find expected lines` error rather than guessing or misapplying the patch. After a file is modified, Atlas immediately invokes the `bash` tool to run `zig build test`. This ensures that the changes integrate correctly with your Zig project's `build.zig` and that no regressions are introduced. Atlas feeds any errors from `zig build test` back into the agent, allowing for iterative correction. Only once the tests pass for a modified file is its corresponding `todowrite` entry marked as completed, guaranteeing a verified migration. ## How does Atlas ensure a complete and safe Zig API migration? Atlas ensures a complete and safe Zig API migration by computing a unified diff for every file edit and surfacing it for approval. Before writing, Atlas uses `git` to snapshot changes, and a final `grep` confirms zero remaining hits of the deprecated symbol, ensuring a 100% clean transition. Safety and transparency are paramount in large-scale migrations. Atlas computes a unified diff for every file edit it proposes, presenting these changes for your explicit approval before writing them to disk. This permission-gated approach means you are always in control. Atlas also integrates with `git`, allowing it to read branches, status, and diffs, and can stage and create commits on your behalf. It snapshots file changes as git patches, so edits can be diffed and rolled back if needed. After all callsites are migrated, Atlas performs a final `grep` for the deprecated symbol across your entire Zig codebase, confirming zero remaining hits. This final verification step, combined with running `zig fmt` on all touched files, ensures a clean, complete, and correctly formatted migration, ready for the old implementation to be safely deleted. ## Steps 1. Enumerate all deprecated API calls in your Zig project: Use `atlas lsp findReferences ` to identify all static usages, then cross-check with `atlas grep ""` for dynamic or string-based references across your `build.zig` and source files. 2. Create a `todowrite` entry for each identified callsite: Atlas will automatically generate a tracked task for every unique usage found, ensuring that no callsite is silently skipped during the migration process. 3. Migrate each callsite using context-anchored patches: Atlas employs `apply_patch` to generate and apply specific changes. This tool seeks the hunk's context and old lines, throwing `Failed to find expected lines` rather than misapplying to a drifted file. 4. Run affected tests and format files after each modification: After Atlas modifies a Zig file, it will execute `atlas bash "zig build test"` to verify functionality and `atlas bash "zig fmt "` to maintain code style, marking the `todowrite` entry complete only upon successful test runs. 5. Review and approve all proposed changes: Atlas computes a unified diff for every file edit and presents it for your approval, allowing you to inspect changes before they are written to your Zig codebase. 6. Confirm zero remaining deprecated symbol usages and delete the old API: Perform a final `atlas grep ""` to ensure no callsites remain, then proceed to delete the original deprecated function or module from your Zig project. ## FAQ ### How does Atlas handle Zig's comptime during API migration? Atlas reads your `build.zig` and `comptime` blocks to understand the architecture, ensuring that API migrations respect Zig's compile-time evaluation and explicit allocator patterns throughout your project. ### Can Atlas integrate with my existing build.zig.zon dependencies? Yes, Atlas can add new dependencies using `zig fetch --save` and wire them into your `build.zig`, then review the `.zon` diff, integrating direct with your Zig package management workflow. ### What if my Zig codebase has custom test runners or build steps? Atlas is designed to read your `build.zig` and understand your project's specific build steps, allowing it to correctly execute `zig build test` or any other custom commands via the `bash` tool behind a permission prompt. ### How does Atlas ensure code quality after a Zig API migration? Atlas runs `zig fmt` on touched files to maintain formatting and `zig build test` after each modification, feeding errors back into the agent for iterative correction, ensuring high code quality in your Zig project. ### Is my Zig code sent to third-party servers for analysis? No, Atlas can build its code index with local Ollama embeddings, keeping your Zig code off third-party servers and ensuring your intellectual property remains secure and private. ### How does Atlas prevent accidental changes to my Zig files? Every Atlas tool call is permission-gated, and it drafts a plan in a read-only agent before execution. It also computes a unified diff for every file edit, requiring your approval before writing any changes to your Zig project. --- Canonical HTML: https://runatlas.sh/resources/stacks/migrate-a-deprecated-api-across-callsites-in-zig Source of truth: aeo_pages row `/resources/stacks/migrate-a-deprecated-api-across-callsites-in-zig` (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.