go: cmd/go: document that gofiles on command line must be in same directory

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

go version go1.9rc2 darwin/amd64

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

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/Dmitri/Dropbox/Work/2013/GoLanding:/Users/Dmitri/Dropbox/Work/2013/GoLand"
GORACE=""
GOROOT="/usr/local/go"
GOTOOLDIR="/usr/local/go/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/tw/kgz4v2kn4n7d7ryg5k_z3dk40000gn/T/go-build182434083=/tmp/go-build -gno-record-gcc-switches -fno-common"
CXX="clang++"
CGO_ENABLED="1"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"

What did you do?

I read https://golang.org/cmd/go/#hdr-Compile_and_run_Go_program, it said:

Usage:

go run [build flags] [-exec xprog] gofiles... [arguments...]

Run compiles and runs the main package comprising the named Go source files. A Go source file is defined to be a file ending in a literal “.go” suffix.

[more details that are not relevant]

Notice there are no restrictions on the prefix of the file, what directory it’s in, or what build constraints the file has.

Then I ran:

mkdir -p $GOPATH/src/new/package
cd $GOPATH/src/new/package
echo 'package main; import "fmt"; func main() { fmt.Println("go") }' > main.go
go run main.go
mv main.go 123.go
go run 123.go
mv 123.go _underscore.go
go run _underscore.go
mv _underscore.go .dot.go
go run .dot.go
mv .dot.go thisis.notgo
go run thisis.notgo
rm thisis.notgo
go run

(Credit goes to @natefinch for discovering this at https://twitter.com/NateTheFinch/status/898585298111787009.)

What did you expect to see?

go
go
go
go
go run: no go files listed
go run: no go files listed

What did you see instead?

go
go
package main: no Go files in /Users/Gopher/go/src/new/package
package main: no Go files in /Users/Gopher/go/src/new/package
go run: no go files listed
go run: no go files listed

It looks like the .go file starting with _ or . gets ignored, probably related to the logic go/build has to ignore files beginning with _ and . in normal Go packages.

Edit: Upon further reading, I think this section from https://golang.org/cmd/go/#hdr-Description_of_package_lists applies and explains the behavior:

As a special case, if the package list is a list of .go files from a single directory, the command is applied to a single synthesized package made up of exactly those files, ignoring any build constraints in those files and ignoring any other files in the directory.

Directory and file names that begin with “.” or “_” are ignored by the go tool, as are directories named “testdata”.