Introduction
Go 1.26 introduces an all-new implementation of the go fix subcommand, crafted to keep your Go code modern and up-to-date. Among its standout features is the source-level inliner, a tool that empowers package authors to create self-service API migrations. In this article, we explore seven crucial aspects of this inliner, from its integration with gopls to its role in automating code upgrades. Whether you're a library maintainer or a daily Go developer, these insights will help you leverage the inliner for cleaner, more maintainable code.
1. What Is Source-Level Inlining?
Source-level inlining replaces a function call with a copy of the function's body, substituting actual arguments for parameters. Unlike compiler inlining, which operates on an intermediate representation and is ephemeral, source-level inlining durably modifies your source code. This makes it ideal for refactoring and API upgrades. For example, calling sum(a, b) can be transformed directly into a + b in your codebase. The algorithm, developed in 2023, handles complex cases like closures, multiple returns, and side effects. If you've used gopls' “Inline call” refactoring in VS Code, you've already experienced this power firsthand.
2. Integration with Gopls for Interactive Refactoring
The inliner is a core building block for several gopls refactorings, including “Change signature” and “Remove unused parameter.” In VS Code, you can trigger it from the “Source Action…” menu. The transformation shown in the Go blog’s before-and-after screenshots illustrates how a call to sum inside six gets expanded. This interactive capability lets you preview and apply inlining on a per-call basis, ensuring you understand the impact before committing. Gopls uses the same underlying engine as go fix, so consistency is guaranteed.
3. Self-Service API Migrations for Package Authors
One of the most exciting applications is enabling package authors to define custom API migrations using //go:fix directives. By annotating functions with these directives, you can specify how calls to deprecated APIs should be transformed. For instance, if you rename a function or change its signature, you can write an inlining rule that automatically updates all callers. This turns go fix into a self-service modernization tool—no need to wait for Google to provide a built-in modernizer. The safety guarantees of the inliner ensure that such migrations don't introduce subtle bugs.
4. Correctness Guarantees: Handling Subtle Edge Cases
Refactoring function calls is fraught with pitfalls: variables captured by closures, side-effect order, and name collisions can break code. The source-level inliner carefully preserves semantics. It renames local variables to avoid shadowing, moves statements to maintain evaluation order, and properly handles multiple return values. This correctness is vital when the inliner is used in an automated tool like go fix, where users expect flawless transformations. The algorithm has been battle-tested in gopls and is now part of the Go toolchain.
5. Comparison with Compiler Inlining
Compiler inlining optimizes performance by copying function bodies into call sites during compilation, but it never touches your source code. Source-level inlining, by contrast, rewrites your files permanently. This distinction matters: compiler inlining is transparent and reversible only by recompiling, while source-level inlining changes the code you commit to version control. Use source-level inlining when you want to eliminate indirection, flatten calls for clarity, or migrate to a new API. The two techniques complement each other—source-level inlining can even produce code that the compiler then further inlines.
6. The Role in the New go fix Command
Go 1.26's revamped go fix command leverages the source-level inliner as one of its analyzers. This means go fix can now apply sophisticated code transformations beyond simple text replacements. For example, it can inline deprecated wrapper functions, update API calls after a signature change, or insert new parameters with default values. The inliner works alongside other bespoke modernizers, but its flexibility makes it a cornerstone of the self-service approach. Running go fix on your project will automatically apply any inlining rules defined by your dependencies.
7. How to Get Started Today
To try the source-level inliner, ensure you have Go 1.26 or later installed. Open a Go file in VS Code with the Go extension, place your cursor on a function call, and open the “Source Action…” menu (Ctrl+. or Cmd+.). Select “Inline call” to see the transformation. For automated migration, add //go:fix inline directives to your package's API functions. Then run go fix ./... to apply all inlinings project-wide. Check the Go blog’s full post for detailed examples and best practices. As the ecosystem adopts these directives, upgrading between library versions will become smoother than ever.
Conclusion
The source-level inliner marks a significant leap forward for Go tooling. By combining interactive refactoring with automated migration, it reduces the friction of API evolution. Package authors gain a way to define modernizers without waiting for upstream changes, while daily developers benefit from more reliable upgrades. As Go continues to emphasize automation and safety, the inliner is a prime example of how small language features can have a large impact on code quality. Start experimenting with it today to future-proof your Go projects.