Mastering Source-Level Inlining with //go:fix in Go 1.26

Overview

The Go 1.26 release introduces a revamped go fix subcommand, designed to help developers keep their codebases modern and consistent. Among its new features is the source-level inliner, a powerful tool that automates the replacement of function calls with the function’s body in your source files. Unlike traditional compiler inlining, which operates on internal representations, this transformation modifies the actual Go source code, making it a durable change you can commit and review.

This tutorial will guide you through using the source-level inliner, both as an interactive refactoring tool (via gopls) and as part of automated project-wide upgrades using //go:fix directives. You’ll learn how package authors can create self-service migration paths for their users, and how to handle common pitfalls.

Prerequisites

• Go 1.26 or later installed (download from go.dev).
• Basic familiarity with Go syntax and command-line tools.
• Optional but recommended: an editor with gopls language server support (e.g., VS Code, Vim, or Emacs).
• A Go module to experiment with (you can create a new one with go mod init example).

Step-by-Step Instructions

1. Using Source-Level Inlining Interactively

The easiest way to see the inliner in action is via your editor. If you use VS Code with the Go extension, place your cursor on a function call, open the “Source Action…” menu (Ctrl+. or Cmd+.), and select “Inline call”. Let’s walk through a concrete example.

Create a file main.go with:

package main

import "fmt"

func sum(a, b int) int {
    return a + b
}

func six() int {
    return sum(3, 3)
}

func main() {
    fmt.Println(six())
}

Now place the cursor on sum(3, 3) inside six(), and trigger the inline action. The result should look like:

func six() int {
    a, b := 3, 3  // introduced temporaries to preserve order
    return a + b
}

The inliner correctly introduces temporary variables to avoid side‑effect issues. If sum had been called with expressions that have side effects (e.g., sum(getA(), getB())), those expressions would be evaluated exactly once before the inlined body.

2. Using go fix with Inline Directives

The same source-level inliner powers go fix when you use a //go:fix directive. This allows package authors to specify that certain function calls should be replaced by their inlined bodies across an entire module.

Assume you maintain a package mylib with a function Double that simply multiplies an integer by two. You decide to inline it directly into callers for performance and simplicity. Write a file mylib/doc.go with:

// Package mylib provides utility functions.
//
//go:fix inline
package mylib

And a file mylib/double.go:

package mylib

// Double returns twice n.
//go:fix inline
func Double(n int) int {
    return n * 2
}

Now in your user’s code, they import mylib and call mylib.Double. To apply the migration, run:

go fix ./...

The tool will replace every call to mylib.Double(x) with x * 2, renaming and adjusting as needed.

You can also combine inline directives with other //go:fix transforms, such as renaming functions or changing signatures. The source-level inliner is one of many modernizers included in go fix.

3. Writing Custom Fix Directives for Your Package

To enable self‑service migrations, add //go:fix inline comments to any function you want to be inlinable. When a downstream user runs go fix, those functions will be inlined automatically. You can also specify conditions or deprecation messages, but the inline directive is the simplest and most powerful.

Important: The inlined body must be safe to substitute. Avoid functions that rely on deferred calls, recover, or closures that capture variables in ways that change semantics after inlining. The tool will warn you if it detects unsafe transformations.

4. Batch Application with go fix

To apply all available //go:fix transforms in your module, including inlining, run:

go fix ./...

You can restrict to a specific package:

go fix ./pkg/...

To preview changes without modifying files, use the -diff flag:

go fix -diff ./...

This prints a unified diff instead of changing files.

Common Mistakes

1. Forgetting to Add the Directive

The //go:fix inline comment must appear immediately before the function declaration (no blank lines). Placing it on a package-level doc block works only if the entire package’s exported functions are to be inlined.

2. Inlining Functions with Side Effects Beyond the Return Value

Functions that modify global state, perform I/O, or have deferred cleanup should rarely be inlined. The inliner will refuse transformations that are clearly unsafe (e.g., if the function contains defer), but you must still exercise judgment.

3. Ignoring Import Statements

After inlining, the original body might reference types or functions that require additional imports in the caller’s file. go fix automatically adds necessary imports, but if the inlined code uses a package that wasn’t imported before, the tool will add it. However, if you manually write a //go:fix directive for a function that calls something from a third-party package, ensure that package is in the user’s dependency graph.

4. Expecting the Inliner to Handle All Cases

The source-level inliner is not a complete program transformation engine. It works for simple, pure(ish) functions. Complex control flow, closures, or recursion may not be inlined safely.

Summary

The source-level inliner in Go 1.26, invoked via interactive refactoring or //go:fix directives, provides a powerful way to modernize Go code. Package authors can offer self‑service API migrations by adding a single comment, while users benefit from automated, safe source transformations. By understanding the prerequisites, following the step‑by‑step examples, and avoiding common pitfalls, you can leverage this tool to keep your Go codebase clean and efficient.