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
- Add a second command under cmd/ that prints the notes as JSON and build both. Which package do they share?
- Move the store package out of internal/ and import it from a second module. What was the compiler error before the move?
- 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.
-
What does cmd/ hold?
Answer
One directory per executable, each with a main package
The directory name becomes the binary name.
-
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.
-
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.
-
What is the module root?
Answer
The directory that contains go.mod
Every import path is relative to the module root.
-
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.
-
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.
-
How is a binary built from cmd/notes?
Answer
go build ./cmd/notes
The path names the package directory.
-
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.
-
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.
-
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