Demystifying Go's Source-Level Inliner in Go 1.26

Go 1.26 brings a revamped go fix command, making it easier to modernize your codebase. A standout feature is the source-level inliner—a tool that allows package authors to define their own API migrations and upgrades. Unlike compiler inlining, which optimizes code internally, source-level inlining rewrites your source code directly. This Q&A explores what the source-level inliner is, how it works, and why it matters for Go development.

# What exactly is source-level inlining in Go?

Source-level inlining replaces a function call with a copy of the function's body, substituting arguments for parameters—but it does this in your source code, not in an intermediate representation. This durable transformation updates your actual files. Go's inliner, first built in 2023, powers gopls's "Inline call" refactoring (available under Source Actions in VS Code). For example, inlining a simple sum function into its call site produces a direct expression. The same inliner is now integrated into go fix as a key analyzer, enabling automated API migrations across your project.

# How does the //go:fix inline directive work?

The //go:fix inline directive (em emphasis on the syntax) lets package authors mark a function as eligible for inlining by go fix. When you run go fix ./..., the tool finds all calls to that function and replaces them with the inlined body. The directive sits in a comment above the function declaration. For instance, if a library deprecates a helper function in favor of a simpler pattern, the author can add //go:fix inline to it. Users then run go fix to automatically update their code, removing the old call and inserting the inlined logic. This is a self-service modernizer that shifts maintenance burden from users to package authors.

# What problems does source-level inlining solve for API migrations?

API migrations often require repetitive, error-prone manual changes across a codebase. Traditional approaches like codemods or search‑and‑replace can miss edge cases. The source-level inliner solves this by performing correct, context‑aware transformations. It handles subtle issues such as name collisions, evaluation order of arguments, and side effects correctly. Package authors can guide users through deprecations by providing a simple directive instead of writing complex codemods. This makes upgrading dependencies smoother and less risky. Beyond migrations, the inliner also supports refactoring tools like “Change Signature” in gopls, because it correctly rewrites call sites after parameter changes.

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

Compiler inlining is an optimization that the Go compiler applies during compilation: it replaces a call with the callee's body in its intermediate representation (IR) before generating machine code. This transformation is ephemeral—it doesn't alter your source files. Source-level inlining, on the other hand, modifies the source code permanently. It's a refactoring tool, not an optimization. While compiler inlining can improve performance, source-level inlining simplifies code maintenance and migration. They use similar substitution logic, but source-level inlining must handle Go's syntax and scoping rules precisely to produce valid, readable source code. Both coexist: compiler inlining enhances runtime efficiency, source-level inlining keeps your source up‑to‑date.

# What subtle correctness issues does the inliner handle?

Inlining a function call involves more than text replacement. The source-level inliner must preserve semantics across several dimensions:

• Name collisions: If the inlined body uses variables that clash with names in the caller's scope, the inliner renames them appropriately.
• Evaluation order: Arguments in Go are evaluated eagerly—the inliner ensures side effects (e.g., function calls as arguments) happen exactly as before.
• Return statements: A function with multiple returns requires transforming those into assignments and control flow (e.g., if blocks) in the caller.
• Deferred calls and panics: Inlining functions that use defer or panic requires careful handling to maintain order and recovery behavior.

By managing these edge cases, the inliner prevents bugs that naïve textual substitution would introduce. This reliability makes it safe to run go fix across large projects.

# What are “self-service” modernizers and how does the inliner enable them?

Self‑service modernizers allow library authors to provide automated upgrade paths without writing complex tools. Instead of shipping a bespoke script or waiting for the Go team to add an official modernizer, authors simply annotate deprecated functions with //go:fix inline. Users then run go fix to apply the inlining across their entire module. This approach scales: every package with Go source can offer its own migration. For example, a logging library that wants to replace a verbose LogWithLevel function with an inlined if check can use the directive. The Go team also provides official modernizers for language features (like iter). The source-level inliner is the first general‑purpose building block that empowers the entire ecosystem to keep code modern.

# How does the inliner integrate with gopls and other tools?

Before appearing in go fix, the source-level inliner powered gopls interactive refactorings. For instance, “Inline call” (found in VS Code's Source Actions) uses the same algorithm. Furthermore, gopls leverages it for “Change Signature” and “Remove Unused Parameter” refactorings. When you change a function's signature, gopls must update every call site. It can inline the old version and then re‑extract a new function? Actually, the inliner helps handle parameter reordering and removal by ensuring that arguments match the new signature correctly. This tight integration means that as the inliner improves, gopls becomes more reliable. In go fix, the inliner runs automatically during a batch upgrade, giving users a consistent experience across interactive and automated workflows.