github.com/daixiang0/gci@v0.13.4/README.md (about) 1 # GCI 2 3 GCI, a tool that controls Go package import order and makes it always deterministic. 4 5 The desired output format is highly configurable and allows for more custom formatting than `goimport` does. 6 7 GCI considers a import block based on AST as below: 8 9 ``` 10 Doc 11 Name Path Comment 12 ``` 13 14 All comments will keep as they were, except the isolated comment blocks. 15 16 The isolated comment blocks like below: 17 18 ``` 19 import ( 20 "fmt" 21 // this line is isolated comment 22 23 // those lines belong to one 24 // isolated comment blocks 25 26 "github.com/daixiang0/gci" 27 ) 28 ``` 29 30 GCI splits all import blocks into different sections, now support six section type: 31 32 - standard: Go official imports, like "fmt" 33 - custom: Custom section, use full and the longest match (match full string first, if multiple matches, use the longest one) 34 - default: All rest import blocks 35 - blank: Put blank imports together in a separate group 36 - dot: Put dot imports together in a separate group 37 - alias: Put alias imports together in a separate group 38 - localmodule: Put imports from local packages in a separate group 39 40 The priority is standard > default > custom > blank > dot > alias > localmodule, all sections sort alphabetically inside. 41 By default, blank, dot, and alias sections are not used, and the corresponding lines end up in the other groups. 42 43 All import blocks use one TAB(`\t`) as Indent. 44 45 Since v0.9.0, GCI always puts C import block as the first. 46 47 **Note**: 48 49 `nolint` is hard to handle at section level, GCI will consider it as a single comment. 50 51 ### LocalModule 52 53 Local module detection is done via reading the module name from the `go.mod` 54 file in *the directory where `gci` is invoked*. This means: 55 56 - This mode works when `gci` is invoked from a module root (i.e. directory 57 containing `go.mod`) 58 - This mode doesn't work with a multi-module setup, i.e. when `gci` is invoked 59 from a directory containing `go.work` (though it would work if invoked from 60 within one of the modules in the workspace) 61 62 ## Installation 63 64 To download and install the highest available release version - 65 66 ```shell 67 go install github.com/daixiang0/gci@latest 68 ``` 69 70 You may also specify a specific version, for example: 71 72 ```shell 73 go install github.com/daixiang0/gci@v0.11.2 74 ``` 75 76 ## Usage 77 78 Now GCI provides two command line methods, mainly for backward compatibility. 79 80 ### New style 81 82 GCI supports three modes of operation 83 84 > **Note** 85 > 86 > Since v0.10.0, the `-s` and `--section` flag can only be used multiple times to specify multiple sections. 87 > For example, you could use `-s standard,default` before, but now you must use `-s standard -s default`. 88 > This breaking change makes it possible for the project to support specifying multiple custom prefixes. (Please see below.) 89 90 ```shell 91 $ gci print -h 92 Print outputs the formatted file. If you want to apply the changes to a file use write instead! 93 94 Usage: 95 gci print path... [flags] 96 97 Aliases: 98 print, output 99 100 Flags: 101 --custom-order Enable custom order of sections 102 -d, --debug Enables debug output from the formatter 103 -h, --help help for print 104 -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]. 105 standard - standard section that Go provides officially, like "fmt" 106 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) 107 default - default section, contains all rest imports 108 blank - blank section, contains all blank imports. 109 dot - dot section, contains all dot imports. (default [standard,default]) 110 alias - alias section, contains all alias imports. 111 localmodule: localmodule section, contains all imports from local packages 112 --skip-generated Skip generated files 113 --skip-vendor Skip files inside vendor directory 114 ``` 115 116 ```shell 117 $ gci write -h 118 Write modifies the specified files in-place 119 120 Usage: 121 gci write path... [flags] 122 123 Aliases: 124 write, overwrite 125 126 Flags: 127 --custom-order Enable custom order of sections 128 -d, --debug Enables debug output from the formatter 129 -h, --help help for write 130 -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]. 131 standard - standard section that Go provides officially, like "fmt" 132 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) 133 default - default section, contains all rest imports 134 blank - blank section, contains all blank imports. 135 dot - dot section, contains all dot imports. (default [standard,default]) 136 alias - alias section, contains all alias imports. 137 localmodule: localmodule section, contains all imports from local packages 138 --skip-generated Skip generated files 139 --skip-vendor Skip files inside vendor directory 140 ``` 141 142 ```shell 143 $ gci list -h 144 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 145 146 Usage: 147 gci list path... [flags] 148 149 Flags: 150 --custom-order Enable custom order of sections 151 -d, --debug Enables debug output from the formatter 152 -h, --help help for list 153 -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]. 154 standard - standard section that Go provides officially, like "fmt" 155 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) 156 default - default section, contains all rest imports 157 blank - blank section, contains all blank imports. 158 dot - dot section, contains all dot imports. (default [standard,default]) 159 alias - alias section, contains all alias imports. 160 localmodule: localmodule section, contains all imports from local packages 161 --skip-generated Skip generated files 162 --skip-vendor Skip files inside vendor directory 163 ``` 164 165 ```shell 166 $ gci diff -h 167 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. 168 169 Usage: 170 gci diff path... [flags] 171 172 Flags: 173 --custom-order Enable custom order of sections 174 -d, --debug Enables debug output from the formatter 175 -h, --help help for diff 176 -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]. 177 standard - standard section that Go provides officially, like "fmt" 178 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) 179 default - default section, contains all rest imports 180 blank - blank section, contains all blank imports. 181 dot - dot section, contains all dot imports. (default [standard,default]) 182 alias - alias section, contains all alias imports. 183 localmodule: localmodule section, contains all imports from local packages 184 --skip-generated Skip generated files 185 --skip-vendor Skip files inside vendor directory 186 ``` 187 188 ### Old style 189 190 ```shell 191 Gci enables automatic formatting of imports in a deterministic manner 192 If you want to integrate this as part of your CI take a look at golangci-lint. 193 194 Usage: 195 gci [-diff | -write] [--local localPackageURLs] path... [flags] 196 gci [command] 197 198 Available Commands: 199 completion Generate the autocompletion script for the specified shell 200 diff Prints a git style diff to STDOUT 201 help Help about any command 202 list Prints filenames that need to be formatted to STDOUT 203 print Outputs the formatted file to STDOUT 204 write Formats the specified files in-place 205 206 Flags: 207 -d, --diff display diffs instead of rewriting files 208 -h, --help help for gci 209 -l, --local strings put imports beginning with this string after 3rd-party packages, separate imports by comma 210 -v, --version version for gci 211 -w, --write write result to (source) file instead of stdout 212 213 Use "gci [command] --help" for more information about a command. 214 ``` 215 216 **Note**:: 217 218 The old style is only for local tests, will be deprecated, please uses new style, `golangci-lint` uses new style as well. 219 220 ## Examples 221 222 Run `gci write -s standard -s default -s "prefix(github.com/daixiang0/gci)" main.go` and you will handle following cases: 223 224 ### simple case 225 226 ```go 227 package main 228 import ( 229 "golang.org/x/tools" 230 231 "fmt" 232 233 "github.com/daixiang0/gci" 234 ) 235 ``` 236 237 to 238 239 ```go 240 package main 241 import ( 242 "fmt" 243 244 "golang.org/x/tools" 245 246 "github.com/daixiang0/gci" 247 ) 248 ``` 249 250 ### with alias 251 252 ```go 253 package main 254 import ( 255 "fmt" 256 go "github.com/golang" 257 "github.com/daixiang0/gci" 258 ) 259 ``` 260 261 to 262 263 ```go 264 package main 265 import ( 266 "fmt" 267 268 go "github.com/golang" 269 270 "github.com/daixiang0/gci" 271 ) 272 ``` 273 274 ### with blank and dot grouping enabled 275 276 ```go 277 package main 278 import ( 279 "fmt" 280 go "github.com/golang" 281 _ "github.com/golang/blank" 282 . "github.com/golang/dot" 283 "github.com/daixiang0/gci" 284 _ "github.com/daixiang0/gci/blank" 285 . "github.com/daixiang0/gci/dot" 286 ) 287 ``` 288 289 to 290 291 ```go 292 package main 293 import ( 294 "fmt" 295 296 go "github.com/golang" 297 298 "github.com/daixiang0/gci" 299 300 _ "github.com/daixiang0/gci/blank" 301 _ "github.com/golang/blank" 302 303 . "github.com/daixiang0/gci/dot" 304 . "github.com/golang/dot" 305 ) 306 ``` 307 308 ### with alias grouping enabled 309 310 ```go 311 package main 312 313 import ( 314 testing "github.com/daixiang0/test" 315 "fmt" 316 317 g "github.com/golang" 318 319 "github.com/daixiang0/gci" 320 "github.com/daixiang0/gci/subtest" 321 ) 322 ``` 323 324 to 325 326 ```go 327 package main 328 329 import ( 330 "fmt" 331 332 "github.com/daixiang0/gci" 333 "github.com/daixiang0/gci/subtest" 334 335 testing "github.com/daixiang0/test" 336 g "github.com/golang" 337 ) 338 ``` 339 340 ### with localmodule grouping enabled 341 342 Assuming this is run on the root of this repo (i.e. where 343 `github.com/daixiang0/gci` is a local module) 344 345 ```go 346 package main 347 348 import ( 349 "os" 350 "github.com/daixiang0/gci/cmd/gci" 351 ) 352 ``` 353 354 to 355 356 ```go 357 package main 358 359 import ( 360 "os" 361 362 "github.com/daixiang0/gci/cmd/gci" 363 ) 364 ``` 365 366 ## TODO 367 368 - Ensure only one blank between `Name` and `Path` in an import block 369 - Ensure only one blank between `Path` and `Comment` in an import block 370 - Format comments 371 - Add more testcases 372 - Support imports completion (please use `goimports` first then use GCI) 373 - Optimize comments 374 - Remove Analyzer layer and fully use analyzer syntax