Go Smart Find Usages
Press Alt+F7 (Option+F7 on macOS) on a Go identifier to see its references grouped by package and file, with production code, tests, generated code, reads, writes, and other usage kinds clearly separated.
No configuration is required. The extension uses the Go Reference and Definition Providers already available in your editor—normally the official Go extension and gopls—without replacing native navigation.
Quick start
- Make sure native Find All References works in the current Go file (normally through the official Go extension and
gopls).
- Place the cursor on a Go function, method, type, field, variable, or parameter.
- Press
Alt+F7 (Option+F7 on macOS), or choose Smart Find Usages from the editor context menu.
- Browse the grouped results in the Smart Usages Sidebar. Start with Mainline, then change the preset or individual checkboxes when needed.
Select a result to preview it, press Enter to keep it open, or use F4 / Shift+F4 to move through visible usages.
Choose a workflow
| What you want |
Command |
Behavior |
| Browse and filter references |
Go Smart Usages: Find Usages (Alt/Option+F7) |
Opens the Filters and Results views in the Sidebar. This is the recommended everyday workflow. |
| Compare definitions and usages |
Go Smart Usages: Peek Definition and Usages |
Opens a dedicated editor-area view with definitions, filtered usages, and source preview. |
| Use VS Code's inline Peek |
Go Smart Usages: Smart Native Peek |
Opens the built-in Peek widget with definitions and a snapshot of the currently visible usages. |
The Sidebar and Smart Definition & Usages Peek share the same query and filters. Smart Native Peek takes a one-time snapshot; run it again after changing filters.
The two Peek commands have no default shortcut. Bind goSmartUsages.peek or goSmartUsages.nativePeek in Preferences: Open Keyboard Shortcuts if desired.
Two Peek modes
Smart Definition & Usages Peek — Extension-owned editor view with filtered usages and source preview.
Smart Native Peek — VS Code's built-in inline widget with definitions and a one-time snapshot of visible usages.
Filters and presets
| Preset |
Shows |
| Mainline (default) |
Semantic usages in production code |
| All semantic |
Semantic usages in every file role |
| Tests only |
Unit-test and external-test usages |
| Writes only |
Writes and read/write usages in production code |
You can also combine individual file-role and usage-kind checkboxes. Filters only change what is visible: the Results title keeps showing visible / total, and excluded locations remain part of the total.
Configuration
The defaults work for most projects. Open Settings and search for Go Smart Find Usages, or add only the overrides you need:
{
"goSmartUsages.defaultPreset": "mainline",
"goSmartUsages.excludePatterns": [
"**/vendor/**",
"**/generated/**"
],
"goSmartUsages.autoRefreshOnSave": true
}
| Setting |
Default |
Use it to |
goSmartUsages.defaultPreset |
mainline |
Choose the preset for new queries. |
goSmartUsages.previewOnSelection |
true |
Preview a result when it is selected. |
goSmartUsages.autoRefreshOnSave |
false |
Refresh after saving a file relevant to the current query. |
goSmartUsages.excludePatterns |
["**/vendor/**"] |
Hide matching workspace-relative paths from Smart Usages. |
goSmartUsages.generatedCodePatterns |
["**/*.gen.go", "**/*_generated.go"] |
Set project-specific generated-code patterns. |
goSmartUsages.additionalTestPatterns |
["**/integration/**", "**/e2e/**"] |
Set additional paths treated as test code. |
goSmartUsages.analysisMode |
auto |
Choose automatic/basic analysis, or warn when deep analysis is unavailable (deep). |
goSmartUsages.historySize |
10 |
Keep 1–50 recent queries in memory. |
Array settings replace their defaults, so keep **/vendor/** when adding your own excludes. Pattern and analysis changes apply to the next query. The extension never writes workspace settings automatically.
Installation
VS Code Marketplace
Open Extensions (Ctrl/Cmd+Shift+X), search for Go Smart Find Usages, verify that the publisher is kizuna-lek, and choose Install.
Install a VSIX from source
Requires Node.js 22+, npm, and Go 1.22+:
npm ci
npm run check
npm run package:vsix
Run Extensions: Install from VSIX... in VS Code or Trae and select the platform-tagged file in release/. See the compatibility matrix for cross-platform build targets.
Requirements
- VS Code 1.85+ or a compatible editor build.
- A working Go Reference Provider, normally the official Go extension with
gopls.
- A local filesystem workspace. Deep classification also requires a trusted workspace.
- A Definition Provider for definition results in either Peek mode. Usages remain available without one.
Trae validation is still pending a concrete Stable target. See Compatibility for the current test status.
Troubleshooting
| Problem |
What to check |
| No references appear |
Confirm that native Find All References works and that gopls is running. |
| Results are classified as Other |
Trust the workspace, keep analysisMode set to auto, and open Go Smart Usages: Open Logs. |
| Everything is hidden |
Apply All semantic, then check goSmartUsages.excludePatterns. |
| Smart Native Peek does not open |
Make sure at least one definition or visible usage exists; otherwise use Peek Definition and Usages. |
Alt/Option+F7 conflicts |
Rebind Go Smart Usages: Find Usages in Keyboard Shortcuts. |
For diagnostics and bug-report guidance, see Support. Product and editor API boundaries are documented in Known limitations.
Scope and privacy
All classification happens locally; the extension makes no network requests and sends no telemetry. See Privacy.
Results are limited to locations returned by the active semantic provider. Comments, strings, reflection, and runtime-generated calls are not scanned. The extension does not replace Go to Definition, Find All References, Rename, Peek References, or Command/Control-click. See Known limitations for the complete scope.
Implementation details are in Architecture. Contributors should start with Contributing; release maintainers should use the publishing checklist.
License
MIT
