In a repo whose root is one module and whose ./cli directory is another, how do you tag the cli module?

## One repository, several modules A repository is not a module. A module is a directory tree rooted at a `go.mod`, and a repository may contain any number of them: a root library plus a `./cli` command with heavier dependencies, a `./examples` module that pulls in things the library should not require, a `./tools` module holding build-time programs. This creates a naming problem. If both the root and `./cli` are released from the same Git repository, a single flat tag namespace cannot say which one `v1.2.0` refers to. Go resolves it by **prefixing the tag with the module's subdirectory**. ### The rule For a module whose `go.mod` is at `<subdir>/go.mod` relative to the repository root, the version tag is `<subdir>/vX.Y.Z`. ``` repo github.com/acme/tools go.mod -> module github.com/acme/tools cli/go.mod -> module github.com/acme/tools/cli git tag v0.7.0 # publishes github.com/acme/tools git tag cli/v1.2.0 # publishes github.com/acme/tools/cli git push origin v0.7.0 cli/v1.2.0 ``` The prefix is the same suffix that distinguishes the two module paths. The root module's tags carry no prefix at all. A nested module two levels deep, `internal-free/tools/gen`, would use `internal-free/tools/gen/v1.0.0`. ### What this buys you **Independent version lines.** The library at the root can stay at v0 while the command is at v1.2.0, or the command can churn through releases without forcing a version bump on library consumers. Nothing in one module's tag stream is visible to the other's consumers. **Independent dependency graphs.** This is usually the real reason to split. A `./cli` module can require an argument parser, a colour library and a config loader without those appearing anywhere in the build of a service that imports only the root library. The root module's `go.mod` never mentions them, because the packages under `cli/` are no longer part of the root module at all — a nested `go.mod` carves that subtree out of its parent. **Independent release cadence** for things that are genuinely different products living in one repository for convenience. ### What it costs **The root module cannot just import the nested one.** Once `./cli` has its own `go.mod`, code in the root module that imports `github.com/acme/tools/cli/...` is importing an external dependency, which must be required at a published version like any other. That is a genuine friction point for a repository that is really one project, and it is the main argument against splitting. **Tagging discipline gets harder.** Two tag streams in one repository means release automation, changelogs and human memory all have to keep the prefix straight. The common failure is pushing `v1.2.0` when you meant `cli/v1.2.0`: the tag exists, the release looks done, and `go get github.com/acme/tools/[email protected]` reports an unknown revision because no tag names that module at that version. Meanwhile you have accidentally published a root-module v1.2.0 you did not intend to promise anything about. **A single commit spans both modules.** Coordinated changes need two tags on possibly the same commit, and reviewers have to notice when a change to the root's API needs a matching release before the nested module can consume it. ### Deciding to split at all Split when the dependency sets genuinely differ and you would be forcing weight onto library consumers otherwise, or when the pieces have different audiences and release rhythms. Do not split merely because directories look tidy: a nested module converts a free internal import into a versioned external dependency with a release step between every change, and that cost is paid on every commit, not just at release time.