GO-PATH(7)                (2021-09-06)                 GO-PATH(7)

     NAME
          go - tool for managing Go source code

     DESCRIPTION
          The Go path is used to resolve import statements.  It is
          implemented by and documented in the go/build package.

          The GOPATH environment variable lists places to look for Go
          code.  On Unix, the value is a colon-separated string.  On
          Windows, the value is a semicolon-separated string.  On Plan
          9, the value is a list.

          If the environment variable is unset, GOPATH defaults to a
          subdirectory named "go" in the user's home directory
          ($HOME/go on Unix, %USERPROFILE% on Windows), unless that
          directory holds a Go distribution.  Run "go env GOPATH" to
          see the current GOPATH.

          See https://golang.org/wiki/SettingGOPATH to set a custom
          GOPATH.

          Each directory listed in GOPATH must have a prescribed
          structure:

          The src directory holds source code. The path below src
          determines the import path or executable name.

          The pkg directory holds installed package objects.  As in
          the Go tree, each target operating system and architecture
          pair has its own subdirectory of pkg (pkg/GOOS_GOARCH).

          If DIR is a directory listed in the GOPATH, a package with
          source in DIR/src/foo/bar can be imported as "foo/bar" and
          has its compiled form installed to
          "DIR/pkg/GOOS_GOARCH/foo/bar.a".

          The bin directory holds compiled commands.  Each command is
          named for its source directory, but only the final element,
          not the entire path. That is, the command with source in
          DIR/src/foo/quux is installed into DIR/bin/quux, not
          DIR/bin/foo/quux. The "foo/" prefix is stripped so that you
          can add DIR/bin to your PATH to get at the installed
          commands. If the GOBIN environment variable is set, commands
          are installed to the directory it names instead of DIR/bin.
          GOBIN must be an absolute path.

          Here's an example directory layout:

     Page 1                       Plan 9             (printed 5/21/22)

     GO-PATH(7)                (2021-09-06)                 GO-PATH(7)

              GOPATH=/home/user/gocode

              /home/user/gocode/
                  src/
                      foo/
                          bar/               (go code in package bar)
                              x.go
                          quux/              (go code in package main)
                              y.go
                  bin/
                      quux                   (installed command)
                  pkg/
                      linux_amd64/
                          foo/
                              bar.a          (installed package object)

          Go searches each directory listed in GOPATH to find source
          code, but new packages are always downloaded into the first
          directory in the list.

          See https://golang.org/doc/code.html for an example.

        GOPATH and Modules
          When using modules, GOPATH is no longer used for resolving
          imports.  However, it is still used to store downloaded
          source code (in GOPATH/pkg/mod) and compiled commands (in
          GOPATH/bin).

        Internal Directories
          Code in or below a directory named "internal" is importable
          only by code in the directory tree rooted at the parent of
          "internal".  Here's an extended version of the directory
          layout above:

              /home/user/go/
                  src/
                      crash/
                          bang/              (go code in package bang)
                              b.go
                      foo/                   (go code in package foo)
                          f.go
                          bar/               (go code in package bar)
                              x.go
                          internal/
                              baz/           (go code in package baz)
                                  z.go
                          quux/              (go code in package main)
                              y.go

          The code in z.go is imported as "foo/internal/baz", but that
          import statement can only appear in source files in the
          subtree rooted at foo. The source files foo/f.go,

     Page 2                       Plan 9             (printed 5/21/22)

     GO-PATH(7)                (2021-09-06)                 GO-PATH(7)

          foo/bar/x.go, and foo/quux/y.go can all import
          "foo/internal/baz", but the source file crash/bang/b.go
          cannot.

          See https://golang.org/s/go14internal for details.

        Vendor Directories
          Go 1.6 includes support for using local copies of external
          dependencies to satisfy imports of those dependencies, often
          referred to as vendoring.

          Code below a directory named "vendor" is importable only by
          code in the directory tree rooted at the parent of "vendor",
          and only using an import path that omits the prefix up to
          and including the vendor element.

          Here's the example from the previous section, but with the
          "internal" directory renamed to "vendor" and a new
          foo/vendor/crash/bang directory added:

              /home/user/go/
                  src/
                      crash/
                          bang/              (go code in package bang)
                              b.go
                      foo/                   (go code in package foo)
                          f.go
                          bar/               (go code in package bar)
                              x.go
                          vendor/
                              crash/
                                  bang/      (go code in package bang)
                                      b.go
                              baz/           (go code in package baz)
                                  z.go
                          quux/              (go code in package main)
                              y.go

          The same visibility rules apply as for internal, but the
          code in z.go is imported as "baz", not as "foo/vendor/baz".

          Code in vendor directories deeper in the source tree shadows
          code in higher directories. Within the subtree rooted at
          foo, an import of "crash/bang" resolves to
          "foo/vendor/crash/bang", not the top-level "crash/bang".

          Code in vendor directories is not subject to import path
          checking (see 'go help importpath').

          When 'go get' checks out or updates a git repository, it now
          also updates submodules.

     Page 3                       Plan 9             (printed 5/21/22)

     GO-PATH(7)                (2021-09-06)                 GO-PATH(7)

          Vendor directories do not affect the placement of new
          repositories being checked out for the first time by 'go
          get': those are always placed in the main GOPATH, never in a
          vendor subtree.

          See https://golang.org/s/go15vendor for details.

     AUTHOR
          This manual page was written by Michael Stapelberg
          <stapelberg@debian.org> and is maintained by the Debian Go
          Compiler Team <team+go-compiler@tracker.debian.org> based on
          the output of 'go help gopath' for the Debian project (and
          may be used by others).

     Page 4                       Plan 9             (printed 5/21/22)