| 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
-
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.
-
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.
-
Verify it still builds and vets:
go build ./... && go vet ./...
-
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.
