Document how using a specific branch of a repo with go modules interacts with multi-module repos

[grantwwu]

What version of Go are you using (go version)?

$ go version
go version go1.12 darwin/amd64

Does this issue reproduce with the latest release?

I believe 1.12 is the latest release

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/grant.wu/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/grant.wu/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/1.12/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.12/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/rm/k4qc6x917tdf1ms2f8t2jw1h0000gp/T/go-build926919438=/tmp/go-build -gno-record-gcc-switches -fno-common"

Description

(I'm not following the bug template here because this is more of a documentation issue)

It's not clear how using a multi-module (or single-module-with-go.mod-not-at-vcs-root) repo interacts with trying to get a particular branch.

Noting that the wiki says:

To upgrade or downgrade to a more specific version, 'go get' allows version selection to be overridden by adding an @Version suffix or "module query" to the package argument, such as go get foo@v1.6.2, go get foo@e3702bed2, or go get foo@'<v1.6.2'.

(https://github.com/golang/go/wiki/Modules#how-to-upgrade-and-downgrade-dependencies)

it's not immediately obvious to me how this interacts with multi-module repos, which require prepending the path. i.e. if I do go get foo@bar/baz/quux, does Go think that I'm trying to get a module rooted at /bar/baz, using the branch quux, or the module rooted at /bar on branch baz/quux?

[bcmills]

go get foo@bar/baz/quux would mean “get module foo at version or branch bar/baz/quux”. (As a general rule, you should never have slashes in the version part of your go get command.)

[bcmills]

go get foo/bar/baz@quux, however, would mean “get module foo/bar/baz at version or branch quux”.

[bcmills]

Folding this into #30850.

[grantwwu]

As a general rule, you should never have slashes in the version part of your go get command.

Git doesn't seem to enforce this requirement (that there are no slashes in a tag or branch name) anywhere. Is this an additional restriction (albeit not a very onerous one) Go is adding?

[bcmills]

No, it's a heuristic to determine whether the thing you're writing as a go get command is likely to be correct.

Technically you could have a branch name with slashes in it. I sincerely doubt that many, if any, repositories containing Go code will have such branches.

[dvcrn]

Branches with slashes are very common, especially with folks using something like git flow

[hausdorff]

Yes, branches with / in them are definitely a thing.

Our situation is: we have to run CI for an OSS project, which requires access to secrets, which means that to run tests, we need to push branches to the central repository, because secrets are not exposed to branches in forks. To avoid multiple developers trampling over each other, we make branches of the form <username>/branchname. This is to say nothing of named branch release patterns, and so on.

[SourceCode]

Branches with slashes are ultra common in workflows. You must be able to isolate a specific branch and even a commit in that branch. An example of this is when a certain forward commit breaks something in a library and you require it frozen in time for whatever reason.

For 4 years we pulled a specific commit of a specific branch for an ORM because anything past would break use cases and this part of the application would not be revisited any time soon by engineers.

Details about / in a branch is as easy as looking up feature branches. - IE: feature/my-feature-ABC-123

In things like Gitlab or other automation tools this allows auto-closing/updating of tickets in other systems as well. Alerting engineers of completion, deployment, etc.

[cespare]

We used to use / for namespacing Git branches at my company, so I guess that's an existence proof that there are indeed repositories containing Go code that have branches with slashes.

That said, this turned out to be a bad idea. Git makes a file for each branch (in .git/refs/heads); if you use slashes in the name, git constructs nested directories. This means that you cannot have two different branches newfeature and newfeature/sub-thing because the directories collide. With a different namespacing character, this isn't a problem.

We switched from / to . a couple of years ago and that has worked well for us.

[SourceCode]

The problem with making those types of changes is that organizations of hundreds / thousands of engineers can't switch code bases, tooling, and existing setups for hundreds of repositories in any timely fashion and to change it because 1 language out of a handful isn't handling it properly seems like crazy talk.

[CyrusNajmabadi]

@bcmills can you reopen this? As people have pointed out (and the many downvotes show) this is definitely something people do and something that is a problem with go's 'heuristic' here. Given that it's completely legal and reasonable to have branch names with slashes in them (which several projects that i'm part of mandate), not being able to use the go tooling effectively here is a significant problem.