Mastering Source-Level Inlining in Go 1.26

By ✦ min read

Welcome to this Q&A guide on the new source-level inliner introduced in Go 1.26's revamped go fix command. This feature helps developers modernize their codebases by automatically replacing function calls with the inline body, enabling straightforward API migrations and upgrades. Below we explore common questions about how it works, its benefits, and practical usage.

What exactly is source-level inlining?

Source-level inlining is a technique that replaces a function call with a copy of the called function's body, substituting actual arguments for parameters. Unlike compiler inlining, which operates on an internal intermediate representation, source-level inlining modifies your actual Go source code files. This means the change is permanent and visible in your repository. For example, if you have a call to sum(a, b) that computes a + b, the inliner would replace the call with a + b directly in your code.

How does source-level inlining differ from traditional compiler inlining?

Traditional compiler inlining is applied during compilation to optimize performance. It works on the compiler's ephemeral intermediate representation, so the source code remains unchanged. In contrast, source-level inlining modifies the actual source files, making it a refactoring tool. While both aim to eliminate function call overhead, source-level inlining is intended for code transformation and modernization, not just optimization. The Go compiler does its own inlining for performance; the source-level inliner is used by tools like gopls and go fix to permanently rewrite code.

Where can I use the source-level inliner today?

The source-level inliner is built into two primary tools. First, it powers the Inline call refactoring in gopls, which you can invoke via the Source Action… menu in VS Code. Second, it is one of the analyzers in the all-new go fix command introduced in Go 1.26. This enables self-service API migrations: package authors can write simple upgrade rules that the inliner executes safely. Additionally, gopls uses it for refactorings like Change signature and Remove unused parameter because it handles many subtle correctness issues.

What makes the source-level inliner safe for refactoring?

When replacing a call with inlined code, many subtle issues can arise, such as variable shadowing, name collisions, and side-effect ordering. The Go team's source-level inliner algorithm carefully handles these cases. For instance, it renames variables to avoid conflicts and preserves evaluation order of arguments. Because it modifies source code permanently, correctness is paramount. The inliner is designed to be conservative: if it cannot guarantee a safe inlining, it will refuse to apply the transformation, preventing bugs from incorrect refactoring.

Can I create my own migration rules using the source-level inliner?

Yes! This is one of the key innovations in Go 1.26. The go fix command allows package authors to define simple API migrations using //go:fix directives. For example, a library maintainer can specify that a deprecated function should be replaced with a new one, and the inliner will automatically substitute calls. This self-service approach means that the Go team doesn't have to write every modernizer themselves—authors can update their own APIs. The rules are expressed in a straightforward way, making it accessible to many developers.

What are the main benefits of using source-level inlining in go fix?

• Automatic modernization: Your codebase stays up-to-date with the latest Go idioms and library APIs without manual effort.
• Reduced maintenance burden: Deprecated functions can be replaced automatically, reducing warnings and future breakage.
• Self-service upgrades: Package authors can distribute upgrade rules, so users can run go fix and instantly migrate.
• Safe transformations: The inliner's careful handling of edge cases means you can trust the result.

Running go fix with source-level inlining is as simple as executing go fix ./... in your project directory.

How does the before-and-after example from the blog post illustrate the inliner?

The original post included screenshots showing a function six that calls a helper sum. After invoking the Inline call refactoring, the call to sum is replaced with its body, making the code simpler and eliminating one level of indirection. This example demonstrates the core action of the source-level inliner: replacing a call site with the function's implementation. Such transformations are especially useful when a helper function is used only once or when its logic needs to be customized inline.