go-rename

name	go-rename
description	Use when renaming a Go symbol (a function, method, type, variable, struct field, or package-level identifier) across a module. Triggers on "rename this go function", "rename X to Y in this package", "rename this symbol everywhere", "rename this variable". Uses `gopls rename` for a type-correct module-wide rename instead of text substitution.
allowed-tools	Bash(gopls *), Bash(go *), Read, Grep, Glob
model	claude-haiku-4-5-20251001
effort	low

Rename a Go symbol correctly across the module with gopls rename. It is type-aware and updates every reference, including across files. Never use sed or find-and-replace for this; those hit unrelated identifiers and miss cross-file uses.

Steps

1. Get the symbol and the new name. If the user gives the name but not the location, find its declaration to get a position:

   grep -rn '<OldName>' --include='*.go' .
   

   You need the exact position of ONE occurrence of the identifier as file:line:col, where col is the 1-based column of the first character of the name.

2. Rename across the module, writing changes in place:

   gopls rename -w <file>:<line>:<col> <NewName>
   

   gopls renames the symbol at that position and all of its references.

3. Verify it still builds and vets:

   go build ./... && go vet ./...
   

4. Report the symbol, old name to new name, the files touched, and the build result.

Rules

• One symbol per invocation. For several renames, repeat the steps.
• Trust gopls over grep counts for finding references; it is semantic, grep is not.
• If gopls says the position is not an identifier, move the column to the first character of the name and retry.
• For a purely syntactic expression rewrite rather than a symbol rename, gofmt -r 'pattern -> replacement' exists, but it is not scope-aware, so prefer gopls rename for identifiers.