gci

GCI

GCI，一個控制 Go 套件匯入順序並使其始終具有確定性的工具。

所需的輸出格式是高度可配置的，並且允許比goimport更多的自訂格式。

GCI 考慮基於 AST 的導入區塊如下：

 Doc
Name Path Comment

除了孤立的評論塊之外，所有評論都將保持原樣。

孤立的評論區塊如下所示：

 import (
  "fmt"
  // this line is isolated comment

  // those lines belong to one
  // isolated comment blocks

  "github.com/daixiang0/gci"
)

GCI 將所有導入區塊拆分為不同的部分，現在支援六種部分類型：

• 標準：Go官方導入，如“fmt”
• custom：自訂部分，使用完整匹配和最長匹配（先匹配完整字串，如果多個匹配，則使用最長匹配）
• 預設值：所有其餘導入區塊
• 空白：將空白導入放在一個單獨的群組中
• dot：將點導入放在一個單獨的群組中
• 別名：將別名匯入放在一個單獨的群組中
• localmodule：將從本機套件匯入的內容放在單獨的群組中

優先順序是標準 > 預設 > 自訂 > 空白 > 點 > 別名 > 本地模組，所有部分按字母順序排序。預設情況下，不使用空白、點和別名部分，並且對應的行最終位於其他群組中。

所有導入區塊都使用一個製表符 ( t ) 作為縮排。

從 v0.9.0 開始，GCI 總是將 C 導入區塊放在第一位。

筆記：

nolint在節級很難處理，GCI 會將其視為單一註解。

本地模組

本地模組檢測是透過從調用gci的目錄中的go.mod檔案中讀取模組名稱來完成的。這意味著：

• 當從模組根（即包含go.mod目錄）呼叫gci時，此模式有效
• 此模式不適用於多模組設置，即當從包含go.work目錄調用gci時（儘管如果從工作區中的模組之一調用，它會起作用）

安裝

要下載並安裝可用的最高發行版本 -

go install github.com/daixiang0/gci@latest

您也可以指定特定版本，例如：

go install github.com/daixiang0/[email protected]

用法

現在GCI提供了兩種命令列方式，主要是為了向後相容。

新款式

GCI支援三種操作模式

筆記

從 v0.10.0 開始， -s和--section標誌只能多次使用來指定多個部分。例如，以前可以使用-s standard,default ，但現在必須使用-s standard -s default 。這項重大變更使該專案可以支援指定多個自訂前綴。 （請參閱下文。）

$ gci print -h
Print outputs the formatted file. If you want to apply the changes to a file use write instead !

Usage:
  gci print path... [flags]

Aliases:
  print, output

Flags:
      --custom-order          Enable custom order of sections
  -d, --debug                 Enables debug output from the formatter
  -h, --help                  help for print
  -s, --section stringArray   Sections define how inputs will be processed. Section names are case-insensitive and may contain parameters in (). The section order is standard > default > custom > blank > dot > alias > localmodule. The default value is [standard,default].
                              standard - standard section that Go provides officially, like " fmt "
                              Prefix(github.com/daixiang0) - custom section, groups all imports with the specified Prefix. Imports will be matched to the longest Prefix. Multiple custom prefixes may be provided, they will be rendered as distinct sections separated by newline. You can regroup multiple prefixes by separating them with comma: Prefix(github.com/daixiang0,gitlab.com/daixiang0,daixiang0)
                              default - default section, contains all rest imports
                              blank - blank section, contains all blank imports.
                              dot - dot section, contains all dot imports. (default [standard,default])
                              alias - alias section, contains all alias imports.
                              localmodule: localmodule section, contains all imports from local packages
      --skip-generated        Skip generated files
      --skip-vendor           Skip files inside vendor directory

$ gci write -h
Write modifies the specified files in-place

Usage:
  gci write path... [flags]

Aliases:
  write, overwrite

Flags:
      --custom-order          Enable custom order of sections
  -d, --debug                 Enables debug output from the formatter
  -h, --help                  help for write
  -s, --section stringArray   Sections define how inputs will be processed. Section names are case-insensitive and may contain parameters in (). The section order is standard > default > custom > blank > dot > alias > localmodule. The default value is [standard,default].
                              standard - standard section that Go provides officially, like " fmt "
                              Prefix(github.com/daixiang0) - custom section, groups all imports with the specified Prefix. Imports will be matched to the longest Prefix. Multiple custom prefixes may be provided, they will be rendered as distinct sections separated by newline. You can regroup multiple prefixes by separating them with comma: Prefix(github.com/daixiang0,gitlab.com/daixiang0,daixiang0)
                              default - default section, contains all rest imports
                              blank - blank section, contains all blank imports.
                              dot - dot section, contains all dot imports. (default [standard,default])
                              alias - alias section, contains all alias imports.
                              localmodule: localmodule section, contains all imports from local packages
      --skip-generated        Skip generated files
      --skip-vendor           Skip files inside vendor directory

$ gci list -h
Prints the filenames that need to be formatted. If you want to show the diff use diff instead, and if you want to apply the changes use write instead

Usage:
  gci list path... [flags]

Flags:
      --custom-order          Enable custom order of sections
  -d, --debug                 Enables debug output from the formatter
  -h, --help                  help for list
  -s, --section stringArray   Sections define how inputs will be processed. Section names are case-insensitive and may contain parameters in (). The section order is standard > default > custom > blank > dot > alias > localmodule. The default value is [standard,default].
                              standard - standard section that Go provides officially, like " fmt "
                              Prefix(github.com/daixiang0) - custom section, groups all imports with the specified Prefix. Imports will be matched to the longest Prefix. Multiple custom prefixes may be provided, they will be rendered as distinct sections separated by newline. You can regroup multiple prefixes by separating them with comma: Prefix(github.com/daixiang0,gitlab.com/daixiang0,daixiang0)
                              default - default section, contains all rest imports
                              blank - blank section, contains all blank imports.
                              dot - dot section, contains all dot imports. (default [standard,default])
                              alias - alias section, contains all alias imports.
                              localmodule: localmodule section, contains all imports from local packages
      --skip-generated        Skip generated files
      --skip-vendor           Skip files inside vendor directory

$ gci diff -h
Diff prints a patch in the style of the diff tool that contains the required changes to the file to make it adhere to the specified formatting.

Usage:
  gci diff path... [flags]

Flags:
      --custom-order          Enable custom order of sections
  -d, --debug                 Enables debug output from the formatter
  -h, --help                  help for diff
  -s, --section stringArray   Sections define how inputs will be processed. Section names are case-insensitive and may contain parameters in (). The section order is standard > default > custom > blank > dot > alias > localmodule. The default value is [standard,default].
                              standard - standard section that Go provides officially, like " fmt "
                              Prefix(github.com/daixiang0) - custom section, groups all imports with the specified Prefix. Imports will be matched to the longest Prefix. Multiple custom prefixes may be provided, they will be rendered as distinct sections separated by newline. You can regroup multiple prefixes by separating them with comma: Prefix(github.com/daixiang0,gitlab.com/daixiang0,daixiang0)
                              default - default section, contains all rest imports
                              blank - blank section, contains all blank imports.
                              dot - dot section, contains all dot imports. (default [standard,default])
                              alias - alias section, contains all alias imports.
                              localmodule: localmodule section, contains all imports from local packages
      --skip-generated        Skip generated files
      --skip-vendor           Skip files inside vendor directory

舊式

Gci enables automatic formatting of imports in a deterministic manner
If you want to integrate this as part of your CI take a look at golangci-lint.

Usage:
  gci [-diff | -w rite] [--local localPackageURLs] path... [flags]
  gci [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  diff        Prints a git style diff to STDOUT
  help        Help about any command
  list        Prints filenames that need to be formatted to STDOUT
  print       Outputs the formatted file to STDOUT
  write       Formats the specified files in-place

Flags:
  -d, --diff            display diffs instead of rewriting files
  -h, --help            help for gci
  -l, --local strings   put imports beginning with this string after 3rd-party packages, separate imports by comma
  -v, --version         version for gci
  -w, --write           write result to (source) file instead of stdout

Use " gci [command] --help " for more information about a command.

筆記：：

舊樣式僅用於本地測試，將被棄用，請使用新樣式， golangci-lint也使用新樣式。

範例

運行gci write -s standard -s default -s "prefix(github.com/daixiang0/gci)" main.go ，您將處理以下情況：

簡單案例

 package main
import (
  "golang.org/x/tools"

  "fmt"

  "github.com/daixiang0/gci"
)

到

 package main
import (
    "fmt"

    "golang.org/x/tools"

    "github.com/daixiang0/gci"
)

有別名

 package main
import (
  "fmt"
  go "github.com/golang"
  "github.com/daixiang0/gci"
)

到

 package main
import (
  "fmt"

  go "github.com/golang"

  "github.com/daixiang0/gci"
)

啟用空白和點分組

 package main
import (
  "fmt"
  go "github.com/golang"
  _ "github.com/golang/blank"
  . "github.com/golang/dot"
  "github.com/daixiang0/gci"
  _ "github.com/daixiang0/gci/blank"
  . "github.com/daixiang0/gci/dot"
)

到

 package main
import (
  "fmt"

  go "github.com/golang"

  "github.com/daixiang0/gci"

  _ "github.com/daixiang0/gci/blank"
  _ "github.com/golang/blank"

  . "github.com/daixiang0/gci/dot"
  . "github.com/golang/dot"
)

啟用別名分組

 package main

import (
	testing "github.com/daixiang0/test"
	"fmt"

	g "github.com/golang"

	"github.com/daixiang0/gci"
	"github.com/daixiang0/gci/subtest"
)

到

 package main

import (
	"fmt"

	"github.com/daixiang0/gci"
	"github.com/daixiang0/gci/subtest"

	testing "github.com/daixiang0/test"
	g "github.com/golang"
)

啟用本機模組分組

假設這是在此儲存庫的根目錄上運行（即github.com/daixiang0/gci是本機模組）

 package main

import (
	"os"
	"github.com/daixiang0/gci/cmd/gci"
)

到

 package main

import (
	"os"

	"github.com/daixiang0/gci/cmd/gci"
)

待辦事項

• 確保導入區塊中的Name和Path之間只有一個空格
• 確保導入區塊中的Path和Comment之間只有一個空格
• 設定評論格式
• 增加更多測試用例
• 支援導入補全（請先使用goimports再使用GCI）
• 優化評論
• 刪除Analyzer層並充分使用Analyzer語法