Go 1.26's Source-Level Inliner: Self-Service API Migrations Made Easy

Introduction

Go 1.26 ships a completely overhauled go fix subcommand, designed to help developers keep their codebases modern and up-to-date with minimal effort. Among its many improvements, one standout feature is the source-level inliner—a tool that empowers package authors to describe simple API migrations and updates in a safe, straightforward manner. This article dives into what the source-level inliner is, how it works, and how you can put it to use right away.

What Is Source-Level Inlining?

Source-level inlining is a transformation that replaces a function call with a copy of the called function's body, substituting the actual arguments for the formal parameters. Unlike traditional compiler inlining, which operates on an internal intermediate representation and is invisible to the programmer, source-level inlining modifies the actual source code files. This durable change makes it ideal for automated refactoring and API migration.

The core algorithm was developed in 2023 and has already been integrated into the Go development ecosystem. If you've used gopls' “Inline call” refactoring (available under the “Source Action…” menu in VS Code), you've already experienced it. The following before-and-after contrast shows the effect of inlining a call to sum inside the six function:

Key Benefits and Use Cases

Source-level inlining is a foundational building block for several important refactoring tools. For instance, gopls uses it to implement the “Change signature” and “Remove unused parameter” refactorings. These operations often involve modifying multiple call sites, and the inliner handles many subtle correctness issues automatically, such as:

• Proper evaluation order of arguments
• Avoiding name collisions
• Preserving side effects

In the context of go fix, the source-level inliner enables self-service API migration. Package authors can provide simple rules that tell the inliner how to replace deprecated calls with new equivalents. For example, an old function OldAPI(a, b) could be inlined and replaced with a call to NewAPI(b, a) along with any necessary adjustments—all without manual intervention.

Example: Migrating an API

Suppose a library decides to rename a function and swap its argument order. Instead of asking every user to manually update each call site, the library maintainer can write a short migration rule. When users run go fix, the source-level inliner automatically transforms the old calls into the new form, updating the source code in place.

Technical Insights

Behind the scenes, the source-level inliner must handle many of the same challenges as a compiler inliner, but with the added complexity of producing human-readable output. Key technical aspects include:

• Precise substitution: Arguments are substituted for parameters, but the inliner must avoid introducing variable shadowing or incorrect scoping.
• Handling side effects: If a parameter is used multiple times in the body and the corresponding argument has side effects, the inliner must generate temporary variables to preserve evaluation order.
• Control flow: The inliner correctly duplicates statements like return, break, and continue while maintaining program semantics.

These capabilities make the inliner suitable not only for simple substitutions but also for complex refactorings that would otherwise be error-prone when done manually.

Getting Started with go fix

To use the new go fix with source-level inlining, you need Go 1.26 or later. Run:

go fix ./...

The tool automatically detects and applies applicable modernizers, including those using source-level inlining. Package authors can configure custom migration rules by providing a fixer definition—consult the official Go documentation for details on the rule format.

Conclusion

The source-level inliner is a powerful addition to Go's tooling ecosystem. By enabling self-service API migration, it reduces the burden on both library maintainers and users, making upgrades smoother and less error-prone. Combined with the overhauled go fix subcommand and gopls' interactive refactoring, it represents a significant step toward keeping Go code modern with minimal friction. Try it out in Go 1.26 and see how it can simplify your project maintenance.