Introduction
Keeping Go code up-to-date with the latest language features and library upgrades can be a challenge. Go 1.26 introduces a revamped go fix subcommand that makes this process easier than ever. At the heart of this new tool is the source-level inliner, a self-service mechanism that allows package authors to define simple API migrations and updates in a safe, automated way. In this article, we explore how the source-level inliner works, how it fits into go fix, and how you can use it to keep your code modern.
What Is Source-Level Inlining?
Inlining is a classic compiler optimization that replaces a function call with a copy of the function's body, substituting actual arguments for parameters. Traditional compilers perform this transformation on an internal intermediate representation, leaving the original source code untouched. Source-level inlining, by contrast, modifies the source code itself—making the change permanent and visible in your project's files.
Go's source-level inliner first appeared in 2023 as an algorithm designed for interactive refactoring. You may already have encountered it through the gopls language server: the Inline call code action (found under Source Action… in VS Code) uses this same machinery. For example, inlining a call to a function named sum inside a six function produces a direct expression like 3 + 3 instead of a function invocation.
How It Works
The source-level inliner performs several careful steps to ensure correctness:
- It identifies the function call to be inlined.
- It retrieves the body of the called function (which may be in the same package or an imported one).
- It substitutes the argument expressions for the formal parameters.
- It handles variable name conflicts by renaming as needed.
- It preserves the original semantics, including returns, side effects, and order of evaluation.
Because the transformation operates on source code, it must account for many subtle correctness issues—such as shadowed variables, side effects in arguments, and differences in control flow. The inliner uses Go's abstract syntax tree (AST) and type information from the go/types package to ensure a faithful transformation.
Using the Source-Level Inliner in Go 1.26
In Go 1.26, the source-level inliner becomes a key component of the new go fix implementation. Package authors can now provide self-service modernizers by annotating functions with a special directive: //go:fix inline. When a developer runs go fix on their project, the tool automatically replaces calls to those annotated functions with the inlined body, applying the migration cleanly across the entire codebase.
For example, suppose a library deprecates a wrapper function oldSum(a, b int) int and wants users to replace all calls with a + b directly. The library author can mark oldSum with //go:fix inline, and every call site will be rewritten automatically when go fix is run. No manual search-and-replace, no risk of breaking changes—just a one-command upgrade.
Practical Applications
Beyond simple function inlining, the source-level inliner enables a range of refactoring and migration tasks:
- API deprecation: Replace a deprecated function with its recommended alternative directly in the caller's code.
- Signature changes: When a function's signature changes (e.g., removing a parameter), the inliner helps rewrite call sites to match.
- Code cleanups: Eliminate unnecessary wrapper functions or adapters, making the code more readable.
- Library upgrades: Update calls to conform to new library APIs without manual editing.
The gopls language server already uses the inliner for interactive refactorings like Change signature and Remove unused parameter. With Go 1.26's go fix, these transformations can be applied project-wide in a single command.
Technical Insights
Building a source-level inliner is non-trivial. The Go team had to solve several challenges:
- Correctness: The inlined code must behave identically to the original call, even when arguments have side effects (e.g., function calls that modify state). The inliner evaluates arguments exactly once and in order.
- Scope and shadowing: Variable names in the inlined body might clash with names in the calling context. The inliner renames variables to avoid conflicts, using fresh names when necessary.
- Multiple return values: Inlining a function with multiple return values requires careful handling, especially when the call appears in an assignment or a short variable declaration.
- Recursive and variadic functions: The inliner handles non-recursive calls; recursion would cause infinite expansion. Variadic functions require special argument substitution logic.
The inliner builds on Go's go/ast and go/types packages, leveraging type information to make safe decisions. It also respects build constraints and generics, ensuring the transformations are applied only where valid.
Conclusion
The source-level inliner transforms how Go developers approach code modernization. By integrating it into go fix and gopls, the Go team has created a powerful yet safe tool for automating API migrations and refactorings. Whether you're a library author providing migration hints or a developer keeping your project current, this feature reduces manual effort and minimizes errors. Go 1.26's go fix is a major step forward in making Go codebases easier to maintain and evolve.