What does a cmd/<name>/main.go layout give a Go repo that ships five binaries?

## Why the directory, not the file, is the unit Go has no notion of a file-level entry point. All `.go` files in one directory belong to one package, and the package named `main` is the one the linker turns into an executable, using its `func main` as the entry point. That single rule produces the whole convention: a repository that ships five programs needs five directories each containing `package main`, because two `func main` declarations in one directory would be a redeclaration in the same package. `cmd/` is simply the agreed place to keep those directories together. ``` repo/ cmd/api/main.go package main cmd/worker/main.go package main cmd/migrate/main.go package main internal/store/ internal/config/ ``` ## What the toolchain does with it - `go build ./cmd/worker` writes an executable named after the package's directory — `worker` — rather than after the file or the package name. That is why the directory names are the product names. - `go build ./...` and `go test ./...` walk the whole tree, so all five programs are covered by one command in CI. - `go install ./cmd/...` builds every main package under `cmd/` at once, which is what a release job usually runs. None of this is required by the go command: a repository with a single binary is perfectly idiomatic with `package main` at its root. `cmd/` earns its place when there is more than one program, or when the root of the repository is a library other people import and you do not want a binary sitting in the middle of it. ## The forcing function A `main` package cannot be imported by anything — the language forbids it. So the moment two binaries need the same code, the layout gives you no lazy option: the shared code must move into a package neither of them owns. In a repository with an `internal/` tree the natural home is `internal/<responsibility>` — `internal/store`, `internal/retry`, `internal/config` — where it is importable by all five binaries and by nobody outside the repository. This is the quiet benefit of the layout. Teams that put logic directly into `main` discover, the second time they need it, that there is no way to reuse it except by copying. Teams that keep `main` to wiring find the extraction has already happened. ## What belongs in main A good `func main` reads like a wiring diagram: - parse flags and environment into a config value; - construct the dependencies (a store, a client, a logger); - start the thing (a server, a consumer loop, a one-shot job); - wait for a signal, shut down, and turn any error into an exit status. Everything else — the request handling, the query, the retry policy, the parsing — belongs in ordinary packages, for two reasons. First, other binaries can then use it. Second, it is directly testable from an ordinary test in that package, rather than only through the assembled program. ## Non-main packages under cmd/ A directory under `cmd/` that is *not* `package main` is an ordinary importable package: `cmd/api/handlers` can be imported by anything, including another repository, unless it sits under an `internal/` directory. That surprises people who assume `cmd/` is itself a privacy boundary. It is not; only `internal/` and the `main` package rule provide any enforcement. If you want a helper that only `cmd/api` uses to stay unreachable, either keep it unexported inside the `main` package itself or put it under `internal/`. ## Common layout mistakes - **One giant main.** Several hundred lines of behaviour in `func main`, none of it importable, none of it directly testable. - **Sharing through cmd/.** Trying to import `cmd/api` from `cmd/worker`; the compiler refuses because it is a `main` package, and the usual reaction — copying the file — is worse than extracting a package. - **Naming the directory after the package instead of the product.** The directory name is what users type, so `cmd/svc-api` yields a binary called `svc-api`; pick the name you want to ship. - **A `cmd/` directory holding one binary in a repository that ships one binary.** Harmless, but it buys nothing over `package main` at the root. ## What an interviewer is checking Mostly that you know the directory-is-a-package rule and can derive the convention from it rather than reciting a layout you copied. The follow-up is usually about where shared code goes, which is where the real design conversation starts.