How do I create a nested go module within a repository?

Question

I'm having difficulty understanding how to structure a go project using packages, especially when this project it nested within a repository.

I would like to have the following folder structure within a repository for my go application.

github.com/user/repo
└── client
└── server
    └── <create go application "package main" code here>
    └── package1
        └── <create package 1 code here>

I want to create my go application/module within the server directory within the repository. However I'm not sure what is the correct or 'best practice' to do so.

1. I'm not sure if the go.mod file should be created within the root directory of the repository or the sub directory server?
2. Should the module name within my go.mod file be github.com/user/repo or github.com/user/repo/server?
3. If I have a package called package1 within a sub directory called package1 of the server folder, what would the import path be to import it?

Answer 1

The general best practice is to put your go.mod file at the root of the repo, and have only one module per repo. Then all of the packages within the repo will be in the same module and share the same dependencies.

It is possible to define multiple modules within a single repository, but doing so adds a lot of maintenance overhead: if you have multiple modules, they are treated as completely separate; you have to explicitly manage the dependencies between them, and you have to explicitly tag separate releases for them.

For most projects, that extra overhead comes with very little benefit: mainly it allows you to tag stable releases for the different modules at different times. In my experience, for most projects that extra flexibility is not worth the maintenance cost.