cmd/go: clarify that special directories can still be used for package paths

[dlsniper]

Hi,

The current documentation is a bit unfortunate when it comes to the special directories understood by the go tool.

https://golang.org/cmd/go/#hdr-Test_packages

The go tool will ignore a directory named "testdata", making it available to hold ancillary data needed by the tests.

https://golang.org/cmd/go/#hdr-Package_lists

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

However, those directories can currently be used just as well for compiling. Unfortunately, I don't have a better wording yet that would describe that only certain operations will behave in this special mode for these special rules/directories.

This comes up often enough as tooling can suggest completion symbols from these directories then users can interpret this as a problem with the tooling rather than special cases in certain go tool usages.

Thank you.

[ianlancetaylor]

Sorry, I'm not sure what you are suggesting. What do you mean when you say "those directories can currently be used just as well for compiling?" Whatever it means, is it an important enough use to be called out in the documentation? Thanks.

[russoj88]

I thought the directory 'testdata' (and sub directories) should only contain test fixtures. My understanding from the docs was that anything placed in 'testdata' would be ignored/undefined during compile.

If I put code in a file called '.code.go', and try to reference it, it results in a compile error (undefined). I can import code from a directory named '.pkg' however. The behavior is at a minimum inconsistent.

I thought that

Directory and file names that begin with "." or "_"

would behave the same as the '.code.go'

[bmuschko]

I'd agree with @russoj88. Can someone define what it really means that testdata is ignored by go tool? What are the implications?

[gomezjdaniel]

I also expect testdata to only contain fixtures, can you clarify this? @ianlancetaylor

[ianlancetaylor]

What it means is that commands like go test ./... will not build code that is under testdata directories. Similarly, the go tool will ignore directories whose names start with "." or "_".

The go tool will not block you from explicitly referring to "testdata" one way or another.

[gomezjdaniel]

will not build code that is under testdata directories

Under testdata directories or under directories whose suffix is testdata? AFAIK is the 2nd

What it means is that commands like go test ./... will not build code ...........

If my 1st assumption is correct (directories that have as suffix testdata) then go test ./... is building for me those directories

--

It is correct to place .go code under testdata folders? e.g. fixtures. If so, the behaviour I would expect is go build command to ignore these folders.

[ianlancetaylor]

Only directories that are literally named testdata will be ignored. There is nothing special about directories whose name has a testdata suffix.

It's fine to put Go files in a testdata directory. You can see many examples in the standard library. The behavior is as I stated: go test ./... will ignore the Go files under a testdata directory. But if you, for example, cd to the directory and run go build, the go tool will build the directory as usual. It won't look up in the file tree to see whether it is underneath a testdata directory.

[matloob]

The behavior was explained in #24732 (comment). Do you think it would be helpful to put that information in go help packages? Maybe the last sentence could be modified to more clearly reference that they are ignored by patterns?

[gopherbot]

Timed out in state WaitingForInfo. Closing.

(I am just a bot, though. Please speak up if this is a mistake or you have the requested information.)