Project Structure
What you will learn
This lesson explains the three levels that organise every Go project, which are modules, packages, and files, and how Go commands choose what to build. You will learn what ./... means, where go build puts its output, and why packages cannot import each other in a circle.
Three levels
| Level | What it is | How you recognise it |
|---|---|---|
| Module | One versioned project with its own dependencies | A folder containing go.mod |
| Package | A set of files compiled together | One directory of .go files with the same package line |
| File | A single source file | A .go file |
The relationship is simple: a module contains packages, and a package contains files. The golden rule is one directory, one package. Every .go file in a directory declares the same package name, and a subdirectory is a different package.
Take this project:
myapp/
├── go.mod
├── main.go
├── cmd/
│ └── tool/
│ └── main.go
└── internal/
└── report/
├── report.go
└── format.go
It is one module with three packages: the root package (main.go), cmd/tool (also a main package), and internal/report (which has two files). Go does not care about the nesting depth. Each directory simply becomes one package.
You first met modules in the Getting Started section. Here is the short version: go mod init <path> creates go.mod, which records the module path and its dependencies.
The module path
The module path is the prefix of every import path inside your project. If go.mod says module example.com/myapp, then the package in internal/report is imported as example.com/myapp/internal/report.
No. For code that stays on your machine, any name works, such as go mod init myapp.
The path only matters when somebody else needs to download your module. Tools like go get treat the module path as an address and look for the code there. If the path is not a real, reachable location, others cannot install your module.
Locally, nothing breaks, because Go only reads go.mod. The trouble starts when someone runs go get against your repository: the path they request and the path declared inside go.mod disagree, and the download fails.
The fix is to change the module line to match the real repository URL (and update the import paths in your code to match).
github.com/yourname/myapp. Renaming later means editing every import.How commands pick a target
Most Go commands work on packages, not on single files. You tell them which packages with a pattern:
| Pattern | Meaning |
|---|---|
. | The package in the current directory |
./cmd/tool | The package in that specific directory |
./... | The current directory and every package below it |
Some examples:
go run . # build and run the package in this folder
go run ./cmd/tool # build and run a different main package
go build ./... # compile everything, to check it all builds
go test ./... # run the tests in every package
You can also run go run main.go to compile a single file, but that ignores the rest of the package, as the previous lesson showed. Prefer ..
Where go build puts its output
go build writes an executable only when the package is a main package. The file is named after the last part of the module path, or the folder you pointed at:
go build . # creates ./myapp (myapp.exe on Windows)
go build ./cmd/tool # creates ./tool
go build -o bin/server . # creates bin/server, a name and place you choose
If you build a package that is not main, Go compiles it to check for errors, but writes no file. go build ./... behaves this way for packages that are libraries.
If you run a Go command outside a module, you may see:
go: go.mod file not found in current directory or any parent directory
Change into your project folder, or run go mod init first.
Visibility follows packages
Because each directory is a package, directories also set visibility boundaries. A lowercase name is visible only inside its own package. So code in cmd/tool cannot call a lowercase function in internal/report, even though both are in one module. It can only call exported (uppercase) names.
The internal directory adds one more rule, enforced by the compiler: a package under internal/ can only be imported by code inside the parent of that internal folder. In the project above, anything in myapp can import internal/report, and no other module can.
Import cycles
Packages form a graph of imports, and that graph must not contain a loop. If package a imports b, then b cannot import a, directly or through other packages:
package example.com/myapp/a
imports example.com/myapp/b
imports example.com/myapp/a: import cycle not allowed
A cycle usually means two packages are too tangled and one responsibility belongs somewhere else. The usual fix is to move the shared piece into a third package that both of them import.
Common mistakes
- Putting two package names in one directory. Go rejects it.
- Using
go run main.goand wondering why other files are missing. Usego run .. - Creating a package for every file. A package is a unit of related code, not one file.
- Importing a package by its folder path alone. The import path starts with the module path.
Practice
A module contains the folders cmd/tool and internal/report. How many packages are involved? Can cmd/tool call an unexported function that lives in internal/report? Which commands would you run to build only the tool, and to test everything?
There are at least two packages, because each directory is its own package (the module root may add a third if it has .go files). cmd/tool cannot call an unexported function in internal/report, because lowercase names are visible only inside their own package. It could call an exported one, and the internal rule allows this import because both live in the same module.
To build only the tool, run go build ./cmd/tool, which writes an executable named tool. To test everything, run go test ./... from the module root.
Summary
A module contains packages and a package contains files, with one directory per package. The module path becomes the prefix of every import path, and it only needs to be a real address when others will download the code. Go commands act on packages through patterns: . for the current one and ./... for everything below. Directories are also visibility boundaries, internal restricts who may import a package, and import cycles are not allowed.
Official reference: How to write Go code.
Ready to wrap up?
Mark this complete when you can explain the main idea and finish the practice task.