Project layout

A Go project is a module directory with packages inside it, and the layout that has become conventional is small: cmd/ holds one directory per executable, internal/ holds the packages that are not part of the public API, and everything else is a package at a path that names it. There is no src directory and no framework: the import path is the directory, and go list ./... is the map of the project. The previous lesson built one binary; this one places it.

The tree

The module path is example.com/notes, so the package in internal/store is imported as example.com/notes/internal/store, and the binary in cmd/notes is built with go build ./cmd/notes. The cmd/ directory exists so a repository can hold two binaries and a library without the binary's package path becoming the module root.

package main import ( "fmt" "os" "example.com/notes/internal/store" ) func main() { s := store.New() s.Add("buy milk") s.Add("write lesson") for i, note := range s.All() { fmt.Printf("%d. %s\n", i+1, note) } fmt.Println("notes:", len(s.All())) os.Exit(0) }

go list ./...

example.com/notes/cmd/notes
example.com/notes/internal/store

go build -o notes ./cmd/notes && ./notes

1. buy milk
2. write lesson
notes: 2

go test ./...

? example.com/notes/cmd/notes [no test files]
ok example.com/notes/internal/store (cached)

go vet ./... && echo vet: clean

vet: clean

go list ./... printed the command and the library, which is the whole import graph of the module. The build produced a binary named after the command directory, the tests passed from the root with one command, and vet said nothing. Those four commands are the whole CI loop of a small project.

What internal means

A package under internal/ can only be imported by code inside the directory that contains the internal directory. Here that is the whole module, so another module cannot import example.com/notes/internal/store even though the import path is public: the compiler refuses it. That is the mechanism that keeps an implementation detail out of the API without a separate repository, and it is the one layout rule the toolchain enforces.

The pkg/ directory that some repositories use is a convention from the early community, not something the toolchain knows; it adds a level to every import and means "public" only because people agreed. A src/ directory is a leftover from GOPATH and changes nothing in module mode except that the module root moves down one level.

How much structure a project needs

A module with ten files can live in the root package and a couple of subdirectories; a module with ten commands needs cmd/ and probably internal/. The rule that scales is to let the import graph be the architecture: a package that everything imports is the core, a package that imports many things is a command, and a cycle is a sign the split is wrong. A directory named after a layer rather than a job (models, utils, helpers) tends to become the package everything imports and nobody owns.

Exercises

  1. Add a second command under cmd/ that prints the notes as JSON and build both. Which package do they share?
  2. Move the store package out of internal/ and import it from a second module. What was the compiler error before the move?
  3. Run go list -f with the imports field on every package and draw the import graph. Which package is the core, and which one is the command?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does cmd/ hold?

    Answer

    One directory per executable, each with a main package

    The directory name becomes the binary name.

  2. What does internal/ enforce?

    Answer

    The package can only be imported inside the parent of internal

    The compiler refuses an import from outside the allowed tree.

  3. What does go list ./... print?

    Answer

    The import paths of all packages under the current directory

    It is the map of the project as the toolchain sees it.

  4. What is the module root?

    Answer

    The directory that contains go.mod

    Every import path is relative to the module root.

  5. What is pkg/ in a Go project?

    Answer

    A community convention, not something the toolchain requires

    It adds a path segment and means public by agreement only.

  6. Where do tests for a package live?

    Answer

    In the same directory as the package

    The test file is compiled with the package it tests.

  7. How is a binary built from cmd/notes?

    Answer

    go build ./cmd/notes

    The path names the package directory.

  8. What is a sign that a package split is wrong?

    Answer

    An import cycle

    The import graph must be acyclic; a cycle means the boundary is misplaced.

  9. Why is a package named utils a problem?

    Answer

    It becomes the package everything imports and nobody owns

    A job name gives a package a reason to exist and a boundary.

  10. What does a src/ directory do in module mode?

    Answer

    Nothing except move the module root down

    It is a remnant of GOPATH.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev