-
Notifications
You must be signed in to change notification settings - Fork 16
/
go_modules.cli.txt
544 lines (467 loc) · 33.5 KB
/
go_modules.cli.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
GO_MODULES
VERSION ==> #See Go language
RELATED DOCUMENTATION ==> #See Go language
/=+===============================+=\
/ : : \
)==: IMPORT PATH :==(
\ :_______________________________: /
\=+===============================+=/
import "IMPORT_PATH" #"IMPORT_PATH" locates the PACKAGE on the filesystem.
#Targets a DIR with *.go
#By convention, DIR name should be same as PACKAGE
#Relative to:
# - GOROOT/src: for standard library
# (if module-aware, and URI)
# - GOMODCACHE
# (if non-module-aware)
# - GOPATH/src
# (if non-module-aware, and start with . or ..)
# - $PWD ("relative IMPORT_PATH")
#When importing PACKAGEs from the same MODULE, IMPORT_PATH must still be full
go tool compile
-D DIR #Relative IMPORT_PATHs base (instead of $PWD)
-nolocalimports #Disallow relative IMPORT_PATHs
-importmap=IMPORT_PATH=IMPORTPATH2#Rename any import "IMPORT_PATH" to import "IMPORT_PATH2"
go tool compile|link
-importcfg=FILE #FILE contains lines with
# - importmap IMPORT_PATH=IMPORT_PATH2: like -importmap
# - packagefile IMPORT_PATH=PATH: like -importmap but using a PATH
ENVVAR GOROOT #Global go directory.
#Contains:
# - binaries (go|gofmt)
# - go tool CMD ... forwards to binaries in ENVVAR GOTOOLDIR (readonly),
# e.g. GOROOT/pkg/tool/GOOS_GOARCH
# - standard library
# - documentation
#Directory structure is non-module-aware one.
#Default: /usr/local/go
#Same directory structure as GOPATH
runtime.GOROOT()->'/PATH' #Returns ENVVAR GOROOT, or the default value for it
ENVVAR GOROOT_FINAL #Allows separating Global go directory sources from built files
go tool compile|asm -I DIR
go tool link -L DIR #Add an alternattive DIR for GOROOT/pkg/GOOS_GOARCH
ENVVAR GOPATH #Same syntax as PATH (:-separated on Unix, ;-separated on Windows)
# - on write, only first element is used
# - usually, having several elements is not needed
#Must be absolute
#Default: ~/go/
#Directory structure:
# - bin/BINARY: binaries, i.e. built main PACKAGEs
# (module-aware)
# - pkg/mod/IMPORT_PATH@vMODULE_VERSION/*.go: source code
# (non-module-aware, or standard library)
# - src/IMPORT_PATH/*.go: source code
# (non-module-aware)
# - pkg/GOOS_GOARCH/IMPORT_PATH/*.a: built non-main PACKAGEs
ENVVAR GOBIN #Userland binaries directory
#Should add both GOBIN and GOROOT/bin to $PATH
#Must be absolute
#Def: GOPATH/bin
ENVVAR GOMODCACHE #If module-aware, where URI-downloaded PACKAGEs are located
#Def: GOPATH/pkg/mod
BINARY INSTALLATION ==> #During go install:
# - if main PACKAGE
# - moved to GOBIN/BINARY
# - BINARY is main PACKAGE's DIR name
#By convention, main package DIR should be:
# - (preferred) REPO_ROOT/cmd/BINARY/
# - REPO_ROOT
go build -pkgdir DIR #Different location for GOPATH/pkg/
IMPORT_PATHS #Is space-separated list of:
# - "IMPORT_PATH[@MODULE_VERSION]"
# - "IMPORT_PATH@none": remove dependency
# - "all": all downloaded PACKAGEs
# - "std": all standard library PACKAGEs
# - "cmd": all go CLI PACKAGEs
# - DIR: packages in DIR *.go or go.mod
# - FILE.go: if several, must all be in same DIR
# - def: "."
#Can contain "..." anywhere:
# - is like a globbing *
# - can expand to 0|1|n PACKAGEs
# - can match empty string
# - often used:
# - ./...: current PACKAGEs
# - ...REPO_PATH: as a shortcut to MODULE_PATH/REPO_PATH
/=+===============================+=\
/ : : \
)==: MODULE PATH :==(
\ :_______________________________: /
\=+===============================+=/
MODULE_PATH #Beginning of IMPORT_PATH.
#Where MODULE is located, i.e. how go get should download it.
#Can be:
# - "": standard libary
# (for github.com, bitbucket.org, launchpad.net)
# - "DOMAIN/USER/PROJECT" for github.com, bitbucket.org, launchpad.net
# (for others)
# - "DOMAIN/USER/PROJECT.git"
# - look for <meta name="go-import" content="MODULE_PATH git SRC_ROOT_DIR">
REPO_PATH #End of IMPORT_PATH.
#PACKAGE path within MODULE.
#If single PACKAGE: often "", i.e. top-level inside repository.
MODULE_PATHS #,-separated list of MODULE_PATH
#Can include globbing
MODULE_PATH_LIST #,-separated list of MODULE_PATH[@vMODULE_VERSION]
#Def to current DIR's MODULE
internal/... #Any PACKAGE within an "internal" DIR can only be imported by:
# - same MODULE
# - and only internal/../**.go, not internal internal/../../**.go
vendor/... #Same except:
# - only "..." must be specified, "MODULE_PATH[/...]/vendor/" can|must be omitted
# - meant for bundling dependencies
#To avoid
vendor/requirements.txt #Similar to go.mod but for vendor/...
go mod vendor #Creates|updates vendor/..., including requirements.txt
-v #Verbose
-e #Do not fail on errors
go build -mod=mod #Ignore vendor/...
go build -mod=vendor #Use vendor/...
#Not needed with Go >=1.14
/=+===============================+=\
/ : : \
)==: REPOSITORY :==(
\ :_______________________________: /
\=+===============================+=/
REPOSITORY STRUCTURE ==> #Due to how go modules work, from repository root:
# - [REPO_PATH/]*.go: non-main PACKAGE
# - [cmd/BINARY/]*.go: main PACKAGE
# - go.mod|sum
GIT ==> #This doc assumes git, but other VCS (svn|mercurial|Bazaar|Fossil) are supported
#which can be customized with ENVVAR GOVCS
go build -insecure #Allow MODULE_PATH to use http: (as opposed to https:)
ENVVAR GOINSECURE #Like -insecure, but as MODULE_PATHS
/=+===============================+=\
/ : : \
)==: VERSION :==(
\ :_______________________________: /
\=+===============================+=/
[v]MODULE_VERSION #MODULE version.
#If specified as argument:
# - MODULE_QUERY
# - git tag|LBRANCH|COMMIT
#Otherwise, by priority order:
# (if module-aware)
# - highest git tag: [DIR/]vA.B.C[-D][+E]
# - DIR is for monorepos
# - latest commit: v0.0.0-YYYYMMDDHHMMSS-XXXXXXXXXXXX
# - last part is git commit hash
# (if non-module-aware)
# - "go1" git branch
# - default git branch
#No prerelease is always preferred over prereleases
#If v, prefixed with v
#"+incompatible":
# - suffix when no MODULE has no go.mod and version is >=2
# - is just an indicator that MODULE upgrades might need additional review
MODULE_QUERY #Query against git tag vA.B.C[-D][+E]:
# - "[<|<=|>=|>]vA[.B][.C][-D][+E]"
# - "latest": vA.*.*
# - "upgrade": vA.*.*, never downgrades
# - "patch": vA.B.*, never downgrades
VERSIONING ==> #go get:
# - if in go.mod or as argument, use it as is (including minor|patch)
# - if -u[=minor|patch], use latest minor (def) or patch instead
# - if competing with other dependencies requiring same dependency,
# use the latest one, even if different major
# - otherwise, use latest major
#Breaking change requires not only new major, but also new IMPORT_PATH
# - reason:
# - only for non-module-aware importers
# - if only module-aware importers, not a problem
# - by convention: append "/vMAJOR" to MODULE_PATH
# - for old Go versions compatibility, can also add a "/vMAJOR" source directory,
# and keep previous version
#Encourages avoiding any breaking changes
# - except for v0.*.*
gopkg.in/[USER/]REPO.vX #One of the many pre-Go-module way to version modules (not necessary anymore)
#URL renamed to github.com/USER/REPO with git branch vX[.Y[.Z]]
# - def USER: go-REPO
/=+===============================+=\
/ : : \
)==: GO.MOD :==(
\ :_______________________________: /
\=+===============================+=/
MODULE ==> #Group of PACKAGEs
ENVVAR GO111MODULE #Decides whether in module-aware mode: "on" (def), "off" or "auto" ("on" if [.../]go.mod exists)
go.mod #File containing line-wise directives (below)
#Location determines the MODULE's root directory:
# - any subdirectory's PACKAGE is included
# - subdirectory with another go.mod are excluded
#Normalized and beautified by any go command that uses it.
#Automatically updated by go get
# - including adding "require ..."
#If updated needed when running go build|test, fails.
#Can be manually edited, then go get will work accordingly.
go build -modfile=PATH #Specify a different go.mod, used for go.mod content.
#Module's normal go.mod is still used to locate module's root.
ENVVAR GOMOD #Absolute "PATH" to current go.mod.
#"" if non-module-aware
#"/dev/null" if none but module-aware
#Read-only
//COMMENT #
module MODULE_PATH #Enforces MODULE_PATH is referred to like this.
#This is in case code is hosted in several places:
# - since MODULE_PATH is used as identifier, having possible duplicates is not good
#This does not declare the MODULE_PATH, since that is defined based by where code is hosted.
package PACKAGE // import #"import comment"
"IMPORT_PATH" #Same but inside source files, using code comment, for non-module-aware
go VERSION #Declares Go version. Used to know which Go features are available at build-time (not runtime)
go tool compile -lang=goX.Y #Target Go version (def: current)
go tool compile -goversion=goX.Y #Exits if current Go version does not match
require MODULE_PATH vMODULE_VRSION
[// indirect] #Declares dependency
require ( #//indirect: dependency's dependency
... # - e.g. when want to control its version
) #Used in deep dependencies
exclude MODULE_PATH vMODULE_VRSION
exclude (
... #Forbid a specific vMODULE_VERSION
) #Not used in deep dependencies
replace MODULE_PATH vMODULE_VRSION
=> vMODULE_VERSION2
replace (
... #Instead of using vMODULE_VERSION, use vMODULE_VERSION2
) #Not used in deep dependencies
retract vMODULE_VERSION
retract [vMODULE_VERSION_START,
vMODULE_VERSION_END]
retract (
... #Do not allow consumers using those versions.
) #Useful to deprecate a version.
go mod init ["MODULE_PATH"] #Creates ./go.mod
#If another Go dependency manager used, migrate it
#Tries to guess MODULE_PATH, e.g. from git info
go mod tidy #Removes unused dependencies from go.mod|sum
#Not done automatically
-v #Verbose
-e #Do not fail on errors
go mod edit [GO_MOD_PATH] #Modifies go.mod
#Does not resolve MODULE|PACKAGEs after modification
-module=GO_MOD_PATH #
-print #Print go.mod after modification
-json #JSON output
-fmt #Normalize|beautify.
#Implied by all other flags
-go=VERSION #Add "go ..."
-require=MODULE_PATH@vMODULE_VERSN#Add "require ..."
#Prefer go get IMPORT_PATH
-droprequire=MODULE_PATH@... #Remove "require ..."
#Prefer go get IMPORT_PATH@none
-[drop]exclude=... #Same with "exclude ..."
-[drop]replace=...=... #Same with "replace ..."
go mod graph #Prints all deep dependencies
#Each line is "MODULE_PATH REQUIRED_MODULE_PATH2"
go mod why IMPORT_PATHS #Prints parent dependencies or deep dependencies
-m #Arguments are MODULE_PATH instead
-vendor #Exclude tests
/=+===============================+=\
/ : : \
)==: LIST :==(
\ :_______________________________: /
\=+===============================+=/
go list IMPORT_PATHS #Prints all PACKAGEs, one per line
-deps #Recursive over dependencies, including standard library
#Print dependency first
-test #Include test binaries
-m #On MODULEs instead
#JSON OBJ is only OBJ.Module
#Def -f flag includes many fields: Path|Version|Replace|Update
#Cannot use -deps, but can use "all" as argument instead
-u #Show latest MODULE_VERSION
#Only with -m
-retracted #Show "retracted" versions (otherwises hidden)
-f TEMPLATE #Of JSON output
#Def: '{{.ImportPath}}'
#Can use template FUNC join (strings.Join())
-json #Prints as JSON OBJ:
# (required)
# ImportPath 'IMPORT_PATH'
# Name 'PACKAGE'
# Dir 'PATH': absolute path to package's DIR
# Root 'PATH': module's root DIR
# Match STR_ARR: CLI arguments in IMPORT_PATHS that matched it
# Module *MODULE: package's module
# Module.Path 'MODULE_PATH'
# Module.Dir 'PATH'
# Module.GoMod 'PATH': of go.mod
# Module.GoVersion 'VERSION': in go.mod
#
# (optional)
# Module.Version 'MODULE_VERSION'
# Module.Versions 'MODULE_VERSION'_ARR: sorted. Only with -versions flag
# Module.Time 'YYYY-MM-DDTHH:MM:SSZ': ctime
# Module.Main BOOL: current directory's MODULE
# Module.Indirect BOOL: go.mod //indirect comment
# Module.Replace *MODULE: go.mod "replace" directive
# Module.Update *MODULE:
# - available update
# - only with -u flag
# Target 'GOBIN/BINARY' or (standard library) GOROOT/pkg/GOOS_GOARCH/**/*.a
# ImportComment 'IMPORT_PATH': from import comment
# Doc STR: documentation comment
# Shlib 'PATH': shared library when using -linkshared
# Goroot BOOL: is in GOROOT
# Standard BOOL: is in standard library
# Stale BOOL: go install would do something
# StaleReason STR: what go install would do
# ConflictDir 'PATH': shadows another PACKAGE in GOPATH
# BinaryOnly BOOL: binary-only PACKAGE (deprecated)
# ForTest STR: only for use in test
# DepOnly BOOL: whether it is a dependency, printed by -deps flag
# Cgo*: CGO settings
#
# (those paths are relative to Dir)
# GoFiles 'PATH'_ARR: *.go, except ones below
# [X]TestGoFiles 'PATH'_ARR: *_test.go inside|outside PACKAGE
# CgoFiles 'PATH'_ARR: *.go importing "C"
# CompiledGoFiles 'PATH'_ARR:
# - *.go sent to compiled
# - is GoFiles + (after processing) CgoFiles|SwigFiles
# - Requires -compiled flag
# IgnoredGoFiles 'PATH'_ARR: ignored *.go
# CFiles 'PATH'_ARR: *.c
# CXXFiles 'PATH'_ARR: *.cc|cxx|cpp
# MFiles 'PATH'_ARR: *.m
# HFiles 'PATH'_ARR: *.h|hh|hpp|hxx
# FFiles 'PATH'_ARR: *.f|F|.for|f90
# SFiles 'PATH'_ARR: *.s
# SwigFiles 'PATH'_ARR: *.swig
# SwigCXXFiles 'PATH'_ARR: *.swigcxx
# SysoFiles 'PATH'_ARR: *.syso
#
# Incomplete BOOL: error while loading information
# (requires -e flag, otherwise prints error on stderr)
# Error *PACKAGE_ERROR
# Error.Err 'MESSAGE'
# Error.ImportStack 'IMPORT_PATH'_ARR: stack trace
# Error.Pos 'FILE:LINE:COL'
# DepsErrors *PACKAGE_ERROR_ARR: errors in dependencies
# Module.Error *MODULE_ERROR
# Module.Error.Err 'MESSAGE'
#
# (unless -find flag)
# Imports 'IMPORT_PATH'_ARR: all import statements, after resolution (e.g. due to vendor/...)
# [X]TestImports 'IMPORT_PATH'_ARR: all import statements, after resolution in *_test.go inside|outside PACKAGE
# ImportMap MAP[STR]STR: key|value is import statement before|after resolution
# Deps 'IMPORT_PATH'_ARR: all dependencies, recursively
# Export 'PATH':
# - binary file in GOCACHE containing information about PACKAGE's exports
# - requires -export flag
#
# (only with -f flag)
# context CONTEXT
# context.GOARCH|GOOS|GOPATH|GOROOT|CgoEnabled STR: like ENVVARs
# context.BuildTags STR_ARR: +build tags
# context.UseAllFiles BOOL: disregard ignored filenames or +build tags
# context.Compiler 'gc|gccgo'
# context.ReleaseTags 'goVERSION'_ARR
# context.InstallSuffix STR
/=+===============================+=\
/ : : \
)==: LIST PROGRAMMATIC :==(
\ :_______________________________: /
\=+===============================+=/
debug.ReadBuildInfo()
->*BUILD_INFO,OK #
debug.BuildInfo #Module information, including dependencies
BUILD_INFO.Path #'MODULE_PATH'
BUILD_INFO.Main #MODULE
BUILD_INFO.Deps #[]*MODULE
runtime.Module #
MODULE.Path #'MODULE_PATH'
MODULE.Version #'MODULE_VERSION'
MODULE.Sum #STR. Module checksum (go.sum)
MODULE.Replace #*MODULE (go.mod replace)
/=+===============================+=\
/ : : \
)==: GET :==(
\ :_______________________________: /
\=+===============================+=/
go get IMPORT_PATHS #Automatically run by go build|test|list
# - including on unknown import "IMPORT_PATH"
#If module-aware:
# - Fetch module over the network
# - Retrieve vMODULE_VERSION
# - Copy source locally to GOMODCACHE/IMPORT_PATH@vMODULE_VERSION
#If non-module-aware:
# - Take local source from GOPATH/src/IMPORT_PATH
# - Build binaries to GOPATH/pkg/GOOS_GOARCH/IMPORT_PATH/*.a
#Build main PACKAGE to GOBIN/BINARY
#If module-aware:
# - Does all of this recursively for dependencies
-d #Does not build main PACKAGE
-u #Upgrade versions of packages already in go.mod
-t #Also get test files
-ANY_GO_BUILD_FLAG #
-v #Verbose
-f #Verify that forks matches the source repository described in MODULE_PATH
#Only if non-module-aware
-fix #Runs go fix on dependencies
#Only if non-module-aware
go install IMPORT_PATHS #Very similar to go get
#Preferred unless -d is needed
go mod download MODULE_PATH_LIST #Like go go get, but with MODULE_PATH, and does not build PACKAGEs
#Prefer go get
-x #Verbose
-json #JSON output
ALTERNATIVE PACKAGE MANAGERS ==> #Alternative package managers have existed before Go 1.11 modules, but are now discouraged.
#This includes: dep, godep, govendor, glide, gom, gop, manul, gvt
/=+===============================+=\
/ : : \
)==: PROXY :==(
\ :_______________________________: /
\=+===============================+=/
ENVVAR GOPROXY #Proxies MODULEs downloads ("module proxy").
#Can be:
# - http[s] URL (GET only)
# - filesystem PATH
# - "direct": no proxy
# - "off": disallow any download
#Can be ,-separated or |-separated list
# - ,: tries next on 404|410
# - |: tries next on any 4**|5**
#Default: "https://proxy.golang.org,direct"
#GOPROXY/MODULE_PATH/:
# - @v:
# - list: line-separated list of all vMODULE_VERSION
# - vMODULE_VERSION.info: JSON with OBJ: Version "vMODULE_VERSION", Time "YYYY-MM-DDTHH:MM:SSZ"
# - vMODULE_VERSION.mod: go.mod content
# - vMODULE_VERSION.zip: MODULE's files. Root dir must be MODULE_PATH@vMODULE_VERSION
# - @latest: same as @v/LATEST_vMODULE_VERSION.info
proxy.golang.org #Goals:
# - better performance
# - using sum.golang.org
# - for Go team to monitor|debug
# - used by pkg.go.dev for package search
#Run by Google
#Cached for few minutes, i.e. takes up to few minutes for new versions to appear
#Can opt-out with GOPROXY=direct
index.golang.org/index #Show latest PACKAGEs added to proxy.golang.org, as JSON feed
#Each OBJ: Version|Time (see above), Path: "MODULE_PATH"
?since=DATE #Def: none
?limit=NUM #Max|def: 2000
ENVVAR GONOPROXY #MODULE_PATHS that should not use GOPROXY
#Can be "none"
ENVVAR GOPRIVATE #Combines GONOPROXY + GONOSUMDB
/=+===============================+=\
/ : : \
)==: INTEGRITY :==(
\ :_______________________________: /
\=+===============================+=/
go.sum #File containing checksum of each package (both go.mod and rest of files), for each vMODULE_VERSION, one per line.
#Sibling to go.mod, created|updated together.
#Goal: integrity when installing again on same|other machine.
#Should be git committed.
go mod verify #Checks that installed packages match their go.sum
go build -modcacherw #Unless this is set, GOROOT|GOPATH/**/go.mod|go.sum|*.go are written with read-only file permissions
ENVVAR GOSUMDB #URL[+PUBLICKEY] to a server that caches PACKAGEs go.sum hashes.
#Only used for PACKAGEs not in local go.sum yet.
#Can be space-separated list
#Can be "off"
#Def: "sum.golang.org"
sum.golang.org #Run by Google
ENVVAR GONOSUMDB #MODULE_PATHS that should not use GOSUMDB
#Can be "none"