`go.alternativeTools` does not override `go.formatTool`

[vanyauhalin]

What version of Go, VS Code & VS Code Go extension are you using?

$ mise version --json | jq -r .version
2025.8.20 macos-arm64 (2025-08-22)

$ go version
go version go1.25.0 darwin/arm64

$ gopls version
golang.org/x/tools/gopls v0.20.0

$ gofumpt --version
v0.9.0+dirty (go1.25.0)

$ code -v
1.103.2
6f17636121051a53c88d3e605c491d22af2ba755
arm64

$ ls ~/.vscode/extensions/ | grep golang.go
golang.go-0.51.0

Describe the bug

This configuration does not work:

{
  "[go]": {
    "editor.defaultFormatter": "golang.go",
    "editor.formatOnSave": true
  },
  "go.alternateTools": {
    "go": "~/.local/share/mise/shims/go",
    "gofumpt": "~/.local/share/mise/shims/gofumpt",
    "gopls": "~/.local/share/mise/shims/gopls"
  },
  "go.formatTool": "gofumpt"
}

This configuration does work:

{
  "[go]": {
    "editor.defaultFormatter": "golang.go",
    "editor.formatOnSave": true
  },
  "go.alternateTools": {
    "customFormatter": "~/.local/share/mise/shims/gofumpt",
    "go": "~/.local/share/mise/shims/go",
    "gopls": "~/.local/share/mise/shims/gopls"
  },
  "go.formatTool": "custom"
}

I expect the go.alternativeTools to override any tool that the extension uses, including go.formatTool.

Relative

#3732 (comment)
#3862

---

Edit:

The "go.formatTool": "gofumpt" works. When I save a file, the extension formats it. The problem is that when I use the "go.formatTool": "custom", the extension catches more cases to format. That tells me that the extension uses its own version of gofumpt, despite that I declare a different path in go.alternateTools to a different version.

[h9jiang]

Hi vanyauhalin,

Thanks for reporting. I did some code reading and I think this is kind of messy. I assume you are using gopls, if gopls is enabled, the formatting will be done by the gopls instead of the extension.

When the language server is enabled and one of default/gofmt/goimports/gofumpt is chosen, the language server will handle formatting. If custom tool is selected, the extension will use the customFormatter tool in the #go.alternateTools# section.

So it's not the extension is handling the formatting, instead, its the gopls.

When custom is being picked, the extension will take care of the formatting. The code in vscode extension is here. The extension only create custom formatter if the formatTool is set to custom. For the rest of the case, it just put undefined

But I think there is another bug, gopls support formatting with gofumpt, but even if you set "go.formatTool": "gofumpt", this is not being sent to gopls. Gopls have an option which accept. So the formatting you are observing is probably the result of go fmt. If you can, please run gopls format file.go to see the format you are observing with "go.formatTool": "gofumpt" is the same as gopls format file.go.

Gopls does allow the LSP client to tell the gopls whether to use gofumpt.

Settings:

- The [`gofumpt`](../settings.md#gofumpt) setting causes gopls to use an
  alternative formatter, [`github.com/mvdan/gofumpt`](https://pkg.go.dev/mvdan.cc/gofumpt).

But this is a boolean value, so what gofumpt being used is determined by the dependency specified by the go.mod file here. See go.mod and gopls source.

If you want to have your own formatter, please use the "custom" formatter.

[vanyauhalin]

Hi h9jiang,

I assume you are using gopls, if gopls is enabled, the formatting will be done by the gopls instead of the extension.

I do know how to check it, but I guess I am, because I can see this in the VSCode Output tab:

[Info  - 9:55:22 AM] 2025/09/22 09:55:20 Created View (#1)
	directory=/Users/vanyauhalin/self/test-golang-extension
	view_type="AdHoc"
	root_dir="file:///Users/vanyauhalin/self/test-golang-extension"
	go_version="go version go1.25.0 darwin/arm64"
	build_flags=[]
	env={GOOS:darwin GOARCH:arm64 GOCACHE:/Users/vanyauhalin/Library/Caches/go-build GOMODCACHE:/Users/vanyauhalin/.local/share/mise/installs/go/1.25.0/packages/pkg/mod GOPATH:/Users/vanyauhalin/.local/share/mise/installs/go/1.25.0/packages GOPRIVATE: GOFLAGS: GO111MODULE: GOTOOLCHAIN:auto GOROOT:/Users/vanyauhalin/.local/share/mise/installs/go/1.25.0 GoVersion:25 GoVersionOutput:go version go1.25.0 darwin/arm64
 ExplicitGOWORK: EffectiveGOPACKAGESDRIVER:}
	env_overlay=[]

[Info  - 9:55:22 AM] 2025/09/22 09:55:21 go/packages.Load #1
	view_id="1"
	snapshot=0
	directory=/Users/vanyauhalin/self/test-golang-extension
	query=[./ builtin]
	packages=2
	duration=217.583ms

The extension only create custom formatter if the formatTool is set to custom.

This part confuses me. Then I first looked at the go.alternateTools, I thought that this option allows me to configure the binary exlicity to tell the extension what to use.

If you can, please run gopls format file.go to see the format you are observing with "go.formatTool": "gofumpt" is the same as gopls format file.go.

The full settings.json:

{
  "[go]": {
    "editor.defaultFormatter": "golang.go",
    "editor.codeActionsOnSave": {
      "source.organizeImports": "never"
    },
    "editor.formatOnSave": true
  },
  "go.alternateTools": {
    "customFormatter": "~/.local/share/mise/shims/gofumpt",
    "go": "~/.local/share/mise/shims/go",
    "gofumpt": "~/.local/share/mise/shims/gofumpt",
    "golangci-lint": "~/.local/share/mise/shims/golangci-lint",
    "golangci-lint-v2": "~/.local/share/mise/shims/golangci-lint",
    "gopls": "~/.local/share/mise/shims/gopls"
  },
  "go.formatTool": "custom",
  "go.lintTool": "golangci-lint-v2",
  "gopls": {
    "importShortcut": "Definition",
    "ui.completion.completeFunctionCalls": false,
    "ui.semanticTokens": true
  }
}

The envs:

$ env | grep GO
GOBIN=/Users/vanyauhalin/.local/share/mise/installs/go/1.25.0/bin
GOPATH=/Users/vanyauhalin/.local/share/mise/installs/go/1.25.0/packages
GOPROXY=direct
GOROOT=/Users/vanyauhalin/.local/share/mise/installs/go/1.25.0

The versions:

$ gopls version
golang.org/x/tools/gopls v0.20.0

$ gofumpt --version
v0.9.0+dirty (go1.25.0)

The source file:

package main

func main () {
	v, err := fn()

	if err != nil {
		v += 1
	}
}

func fn() (int, error) {
	return 0, nil
}

The result of gopls format main.go:

package main

func main() {
	v, err := fn()

	if err != nil {
		v += 1
	}
}

func fn() (int, error) {
	return 0, nil
}

The result of saving file in the editor:

package main

func main() {
	v, err := fn()
	if err != nil {
		v += 1
	}
}

func fn() (int, error) {
	return 0, nil
}

The gopls format removed the space before () in the func main, but did not remove the newline before the if err.

If you want to have your own formatter, please use the "custom" formatter.

This is what I am doing right now. I just thought I could set the path to the correct binary of the "gofumpt" instead of using the "custom".

[h9jiang]

Hi vanyauhalin@,

I think the current behavior is not ideal. I will try to make the formatter and linter behavior align. I have no idea why they are not aligned in the first place.

My best guess would be: gopls was trying to be a single source of the formatter by introducing the support for gofumpt. But it is not comprehensive (because it only support one version of gofumpt and does not support other formatters) so the vscode extension pre-maturely migrate the formatter's job to gopls.

To make this aligned, we can ask the formatter configuration to behave the same as the linter. Pick alternateTool if available.

Do you think this kind of change is something you would expect? Is that possible to consolidate two issues into one?

[vanyauhalin]

To make this aligned, we can ask the formatter configuration to behave the same as the linter. Pick alternateTool if available.

Yes, this is exactly what I would expect.

Is that possible to consolidate two issues into one?

Ye, reasonable.

---

In #3862 you mentioned that:

But what is not intended is, the extension should not try to install the tool because the user already specified the alternate tool.

If this is already fixed, then #3862 could be closed.

[gopherbot]

Change https://go.dev/cl/713200 mentions this issue: extension/src: run formatter specified from setting "go.formatTool"

[gopherbot]

Change https://go.dev/cl/713620 mentions this issue: extension/src: validate format tool settings

[gopherbot]

Change https://go.dev/cl/713940 mentions this issue: CHANGELOG.md: include tool management refactoring entry