« Back to Index

Go: ‘Application’ and ‘Workspace’ Directory Structure

View original Gist on GitHub

Tags: #go #project

Golang ‘Application’ and ‘Workspace’ Directory Structure.md

Workspace

This information was copied from an older article, which didn’t cover Go Modules.
https://www.digitalocean.com/community/tutorials/understanding-the-gopath

Inside of a Go Workspace, or GOPATH, there are three directories: bin, pkg, and src. Each of these directories has special meaning to the Go tool chain.

bin

The $GOPATH/bin directory is where Go places binaries that go install compiles. Our operating system uses the $PATH environment variable to find binary applications that can execute without a full path. It is recommended to add this directory to our global $PATH variable.

pkg

The $GOPATH/pkg directory is where Go stores pre-compiled object files to speed up subsequent compiling of programs. Typically, most developers won’t need to access this directory. If you experience issues with compilation, you can safely delete this directory and Go will then rebuild it.

src

The src directory is where all of our .go files, or source code, must be located (pre 1.13 when go modules were introduced!). This shouldn’t be confused with the source code the Go tooling uses, which is located at the $GOROOT. As we write Go applications, packages, and libraries, we will place these files under $GOPATH/src/path/to/code.

Application Structure

In order of priority:

• https://blog.golang.org/organizing-go-code
• https://rakyll.org/style-packages/
• https://peter.bourgon.org/go-best-practices-2016/#repository-structure
• https://github.com/golang-standards/project-layout (unofficial, and generally frowned upon by official go authors †)

† https://github.com/golang-standards/project-layout/issues/117

One of the Google Go authors states:

For the record, the minimal standard layout for an importable Go repo is really:

• Put a LICENSE file in your root
• Put a go.mod file in your root
• Put Go code in your repo, in the root or organized into a directory tree as you see fit

That’s it. That’s the “standard”.

In particular:

• It is not required to put commands in cmd/.
• It is not required to put packages in pkg/.
• It is not required to put web stuff in web/.
• It is not required to put APIs in api/.
• It is not required to put web stuff in web/.
• It is not required to put configurations in configs/.
• It is not required to put systemd scripts in init/.
• It is not required to put shell scripts in scripts/.
• It is not required to put Docker files in build/package/.
• It is not required to put CI configs in build/ci/.
• It is not required to put deployment configs in deployments/.
• It is not required to put test support in test/.
• It is not required to put documentation in docs/.
• It is not required to put supporting tools in tools/.
• It is not required to put examples in examples/.
• It is not required to put third_party code in third_party/.
• It is not required to put git hooks in githooks/
• It is not required to put static assets in assets/.
• It is not required to put website data in website/.

The importable golang.org/x repos break every one of these “rules”.