assets/formatters: update the GCI documentation

[stevekuznetsov]

The gci tool does not format code - it only ensures that import blocks are formatted deterministically, according to the configuration. The previous documentation blurb looks like it may have been copy-pasted from some of the other formatter docs, and was misleading at best.

[CLAassistant]

All committers have signed the CLA.

[boring-cyborg]

Hey, thank you for opening your first Pull Request !

[ldez]

Sorry but gci format the code.
And this file is generated.

[stevekuznetsov]

@ldez this is simply not true. Please test it out yourself ... here's a commit where without gofmt there is no formatting: Azure/ARO-Tools@7000474

[ldez]

@stevekuznetsov This is simply true, but you are thinking that gofmt is the default formatter in Go, which is not the case.

There is go fmt and gofmt, and they are different:

• go fmt is the core Go formatter https://github.com/golang/go/blob/1cf6386b5ee1ba7d367b6456c2c6888ab68c3ec8/src/go/format/format.go#L101
• gofmt is an extended version of the core Go formatter https://github.com/golang/go/tree/master/src/cmd/gofmt

gci uses the core Go formatter and so formats ALL the code and not only the imports.

[stevekuznetsov]

@ldez I am providing you exactly the steps to reproduce this .... why don't you try it instead of closing my issues?

I have sent you the exact repo you can test it with and exactly the commands I am running. golangci-lint fmt with ONLY gci simply does not format Go source files. Please let me know if you are not able to reproduce this? The steps are fairly straightforward.

[ldez]

Why don't you read my previous comment?

[stevekuznetsov]

I am showing you the diff with go fmt ./... - which IS the core formatter, and is formatting files that gci does not touch.

[stevekuznetsov]

Here is the full reproducer starting from a fresh clone.

$ git clone https://github.com/Azure/ARO-Tools.git
Cloning into 'ARO-Tools'...
remote: Enumerating objects: 838, done.
remote: Counting objects: 100% (137/137), done.
remote: Compressing objects: 100% (90/90), done.
remote: Total 838 (delta 72), reused 79 (delta 46), pack-reused 701 (from 1)
Receiving objects: 100% (838/838), 306.06 KiB | 1.96 MiB/s, done.
Resolving deltas: 100% (505/505), done.
$ cd ARO-Tools/
$ cat .golangci.yaml 
version: "2"
formatters:
  enable:
    - gci
  settings:
    gci:
      custom-order: true
      sections:
        - standard
        - default
        - prefix(k8s.io)
        - prefix(sigs.k8s.io)
        - prefix(github.com/Azure)
        - blank
        - dot
$ go tool golangci-lint fmt -v
INFO golangci-lint has version v2.0.2 built with go1.24.4 from (unknown, modified: ?, mod sum: "h1:dMCC8ikPiLDvHMFy3+XypSAuGDBOLzwWqqamer+bWsY=") on (unknown) 
INFO [config_reader] Config search paths: [./ /tmp/ARO-Tools /tmp / /home/stevekuznetsov] 
INFO [config_reader] Used config file .golangci.yaml 
INFO Formatting Go files...         
$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean
$ go fmt ./...
pkg/config/ev2config/sanitizer/sanitizedconfig.go
pkg/types/shell.go
$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   pkg/config/ev2config/sanitizer/sanitizedconfig.go
	modified:   pkg/types/shell.go

no changes added to commit (use "git add" and/or "git commit -a")

[ldez]

In fact, the code should be formatted based on the gci code.
I think there is a bug, I will check that.

[ldez]

Ok this is a type of "bug" of gci:

package main

import (
	"fmt"

	"os"
)

type Foo struct {
Value string
}

The code is formatted only if the imports are updated by gci.

So I was right: gci formats all the code.

[stevekuznetsov]

Unless gci is updated to unconditionally format the code, users must provide multiple formatters in the golangci-lint config to get a working format experience. Not a "bug" in air-quotes, a full-on bug. Any reasonable user will expect formatters being specified and running golangci-lint run --fix or golangci-lint fmt in CI will mean they guarantee that their code is formatted.

[ldez]

#5893

[ldez]

There are air-quotes because this is intentional from the POV of gci.

But obviously this is not expected from the POV of golangci-lint.

[ldez]

The situation is an illustration of why it's better to open an issue before opening a PR.

You have opened a PR that modifies a generated file, and said something false from my POV.
I tried to explain to you what I was guessing to be the problem, but you opened a second PR with the same content, instead of continuing the discussion here.

If an issue had been opened, I think the situation would have been different.

At the end, we found a bug, but the experience was not good for you and me.

Sorry if you experienced this as rude, but your approach was not right either.

The problem will be fixed, and in the future, I hope we will remember this story as a simple misunderstanding.

[stevekuznetsov]

Dismissive comment + immediately closing the issue doesn't just experience as rude, it is rude. Asking a simple question for clarification and keeping the issue open wouldn't hurt you one bit, would it?

[ldez]

You are not happy, I heard it.

I tried to de-escalate, but you don't want to.

This ends the discussion.
Sorry for not meeting your expectations.