Thanks for showing how to name the directories. I also need to know how to:

1. Add library code
2. Import library code into a binary
3. Build a binary
4. Perform offline builds

How about adding some example code? Ideally, this would be a complete buildable repository with short .go files and Makefile that show best practices for building, running tests, linting, etc.

It would be great to incorporate the solution for golang/go#37554 , to save folks from having to understand 27 pages of technical discussion.

These things are not at all obvious. For example, the obvious command go build ... does not produce any binaries. Running go build -v ... produces no output and go build -vvv ... doesn't work. And if I manage to produce a binary with go build cmd/example/example.go, the corresponding go clean does not delete it. Please put the appropriate commands in Makefile.

Here's example code to get started:

// go.mod
// Allow others to import this module into their projects or use `go install`:
module github.com/org1/example
// For private code:
//module _/example

go 1.14

// lib1/lib1.go
package lib1

import "fmt"

func Func1() {
	fmt.Println("lib1.Func1()")
}

// pkg/lib2/lib2.go
package lib2

import "fmt"

func Func2() {
	fmt.Println("lib2.Func2()")
}

// cmd/example/example.go
package main

import (
	"github.com/org1/example/lib1"
	"github.com/org1/example/pkg/lib2"
	// "_/example/lib1"
	// "_/example/pkg/lib2"
)

func main() {
	lib1.Func1()
	lib2.Func2()
}

# Makefile
#GOCACHE=output/cache/ fails with "GOCACHE is not an absolute path"
GO_BUILD=go build -pkgdir output/pkg/ -i -o output/ -v -trimpath
buid: mkoutput
	${GO_BUILD} ./...

mkoutput:
	mkdir -p output/ output/pkg/

clean:
	rm -rf output/

$ make
mkdir -p output/ output/pkg/
go build -pkgdir output/pkg/ -i -o output/ -v -trimpath ./...
runtime/internal/sys
math/bits
internal/race
unicode/utf8
unicode
runtime/internal/atomic
internal/cpu
sync/atomic
runtime/internal/math
internal/testlog
internal/bytealg
math
runtime
internal/reflectlite
sync
errors
sort
internal/oserror
io
strconv
syscall
reflect
internal/syscall/execenv
internal/syscall/unix
time
internal/poll
os
internal/fmtsort
fmt
github.com/org1/example/lib1
github.com/org1/example/pkg/lib2
github.com/org1/example/cmd/example
$ ls -alF output/
total 4240
drwxr-xr-x   4 user  staff      128 Jul  9 17:03 ./
drwxr-xr-x   8 user  staff      256 Jul  9 17:03 ../
-rwxr-xr-x   1 user  staff  2170120 Jul  9 17:03 example*
drwxr-xr-x  20 user  staff      640 Jul  9 17:03 pkg/
$ ./output/example 
lib1.Func1()
lib2.Func2()
$ make clean
rm -rf output/
$

Edit: Added alternative _/example module name. Ran go clean -cache and now build command shows output.

Generally I'm still unsure about pkg, but lets keep that there #10. It still applies that you need your lib for external use must be independent from internal stuff.

Assuming I'd like to follow the current project-layout consensus, especially /pkg and /internal:
I have a lib implementing this requiring the implementer to return its app's current version here.

Now, the app's current version lays perfectly somewhere in /internal and I really like not to have an include into /internal.

1. I could define a version string parameter, Version field in a struct or SetVersion(version string) method and such. That approach looks messy, as I probably would have to carry that option multiple "layers", but the caller has ultimate choice. But I don't like the option at all, that the caller has to set a version...
2. I could also see, that the resulting version is indeed dependent from my lib (code-wise), but the meaning of that field is definitely practical (should return the version of the binary running - so not the "lib-version")
3. It could depend on the "caller/user" to either want 1. or 2. (= variant 1, or set it with help of 2. with the package variable).
4. But this package variable is set on build-time with -ldflags, so someone importing that code will never get the real version.

Your thoughts from your angle?

When using "Standard Go Project Layout" I face serious issue with /web directory, which in my case contains really big frontend project. I'm working with yarn workspaces in that folder, so when I run for instance go mod tidy command I'm getting the following warnings:

warning: ignoring symlink /home/sysadmin/Documents/<project>/web/node_modules/<some package>

Also I'm not sure if scanning entire /web folder for anything related to Go is very effecient.
So one possible solution is to rename /web to /_web.

P.S. running go help packages we get the following:

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

What would be the approach to deploy the cmd/<name>/main.go structure to Google App Engine?

The regular command gcloud app deploy --project=<whatever> won't pick up that the main file is in another folder, and the entry file cannot be specified to the command.

I suppose the only hack-around would be to put the main.go in the base directory for deployment purposes? Feels dirty.

The existence of this repository is harmful for Go beginners. People arrive here from Google searches, looking for ways to structure their small, simple packages. What they find is overwhelming, at the least.

It has several serious issues:

1. No go.mod file, while modules are becoming a standard for Go dependency management
2. Suggests to place all exportable code in pkg/, which is outdated advice and no longer recommended for Go projects (as it adds a superfluous path component to every import).
3. Has a large number of directories, most of which aren't needed by 99% of projects

Please either spend some time to modernize this project, or delete it

Happy to see this attempt, but none of the decisions or suggestions are explained.

If there are valid reasons to use such a structure, it should be easy to list those reasons.

As someone who has my own preferred structure, I would need some reasons to switch. "Unifying everyone's structure" is a great argument for a unified structure, but not necessarily this structure.

The examples folder seems to conflict with: Use singular form for collection repo/folder name. Thoughts?

Hi,

I've created this question https://stackoverflow.com/questions/47788850/go-project-structure-best-practise in stack overflow and I wonder if the repo author can give is insight.

Thanks,
Sofia

Hi, guys!

Thanks for repo, it's useful.
But I confused about a place of templates, localization files, sql files in the project structure. What do you think about that?

The name organization name golang-standards is misleading for beginners and people new to Go. It implies that the included repositories - which are misleading as well, btw - conclude official standards, which is definitly not the case.

Go language documentation itself suggested to use the src directory. Why did you mention in your README that src should not be used.

https://golang.org/doc/code.html

where put paths and router to make an API in this arquitecture

If I want to add the Japanese version, should I add a file like README_ja.md ?

Also, when reviewing, I plan to have some Japanese people look at it.

I was wondering what the internal/app directory was for, exactly. The README.md says:

Put your actual application code in the /internal/app directory

What does it mean by your "actual application code"? I thought that application code goes in the /cmd/<app_name>/ directory. And if it's not part of the main package, shouldn't it then, by definition, be a package that belongs in either /pkg/ or /internal/pkg/?

I've been placing internal packages directly in the /internal/ directory, and it's been working out well. I know this repo is simply a suggestion, and I might continue to do what I've been doing, but it would be awesome if you could explain to me why you chose the way that the docs suggest, as it might be better than my way for reasons I don't yet know. Thanks!

Where should the generated Log and similar files be stored?

Named a storage floader in the root directory?

It would be really helpful if you can give an example on how to use this layout for gRPC based microservice systems, since gRPC and Microservices are quiet common now a days.

The general consensus of the Go community has been converging on the idea that the pkg/ directory is a useless abstraction / indirection. Instead, people are encouraged to either put the packages in the top-level of the repository, or to create a repository structure that structures things based on their primary functionality of domain in the business logic.

So while in your example you may encourage people to have the following layout:

pkg/
  server/
    handlers/
  poller/
    config/
    manager/

We instead would prefer:

server/
  handlers/
poller/
  config/
  manager/

This may seem innocuous, but because this project has asserted itself as some sort of Go standards body what is being recommended here is being taken seriously. In the Slack workspace, where there are over 30k registered users, we quite often need to correct people who are using pkg/ and have them ignore the recommendations here. Some of the things recommended here are good, and I'd like to be able to use them as a resource. That said, considering the current pkg/ recommendation we're hard-pressed to use this as a resource because we have to tell people to ignore certain parts.

Hello,

It seems godoc can't find this project. My best guess is because there's no go files in this project. However, I'm getting the same behavior in a project of mine which has go files, just not in root directory. You can see by the broken badges in README.md. Any suggestions regarding the best way to solve this? Rethink this aspect of the project structure or check with the guys in godoc to see what can be done over there?

I've a service account file generated by Google which contains (secret) keys. I can't conclude from the current setup where to put these into.

My first idea was configs. But for me, configs can be public.

hi,
where to store cgo files? such as .h .so?

I am building a microservices project with services written in Go, Python and JavaScript for the frontend, what is the best way to structure a multi language monorepo?

Every document or blog I have found are merely some simple helloworld crap with a single directory of source files and no external libraries.

I'm trying to convert my k8s controller to using go modules because getting our CI/CD system to work with dep is an ungodly nightmare.

Is there a good doc or example of someone using go modules with a complex directory structure of many go packages at multiple levels?

What a hair-pulling nightmare go dependencies are.

Hey,

I was wonderin what you think about the official Go documentation, which recommends creating a src folder, whereas you tell us not to.

Here's the link: https://golang.org/doc/code.html

Is there a best practice in GO for file server path name?

I can imagine "/files" or "/static".

What do you think?

This repo owner confuses beginners (golang-standards), actually its' not a standard. It's just an opinion of a group of coders and historical reasons as it's mentioned in the README and part of the project structure is a bad practice ( like vendor or pkg directories, we have something called mods now!) . I suggest to move this project to another organization called "golang-non-standard" or remove it.

Why "web/template" (singular) instead of "web/templates" (plural)?

Please, delete this repo, because it brings nothing else but confusion and encourages bad practices in go (a lot around naming) especially for beginners.

Especially it's bad when new go developers start to advocate bad practices and use this repo as a reference.

Instead, create a list of resources that would bring knowledge about the "industry standards" (the way how go is written in stdlib)

Like those:

0. Go basics

https://tour.golang.org/welcome/1
https://gobyexample.com/
https://blog.golang.org/context
https://ekocaman.com/go-context-c44d681da2e8

Would highly recommend to read this even if you’re advanced Gopher - http://devs.cloudimmunity.com/gotchas-and-common-mistakes-in-go-golang/

1. Style guideline for Go packages

https://rakyll.org/style-packages/

One of the famous figures and main contributors to Go language, Rakyll, writes about importance of naming and structuring of the packages.

2. Effective Go

https://golang.org/doc/effective_go.html

Effective Go article is a community evangel of how effective Go code should be written.

3. Code Review Comments

https://github.com/golang/go/wiki/CodeReviewComments

Wiki page from Go repository with idiomatic code habits that would help you to avoid traps of trying to write Java (or C#, or TypeScript, or Javascript) in Go which never works.

4. Structuring applications for Growth in Go

https://www.youtube.com/watch?v=LMSbsW1Xpwg
In this lightning talk, Ben Johnson gives a quick idea of what kind of issues you might face with inappropriate project structure

5. Best Practices for Industrial Programming

https://www.youtube.com/watch?v=PTE4VJIdHPg
Peter Bourgon dives deeper into the ways of setting up the project structure that are more adopted within the industry, providing also more justifications on an issues that he was facing on his Go journey. A lot of his practices are widely used within the Go community.

What is a common approach when project is using a protobuf and gRPC?

• Where to keep *.proto files?
• Where should be generated files placed, near to protobuf declarations or in another place?
• Any other tips to build clean folder layout when using protobuf and grpc?

Thanks to everyone!

Hi, I was wondering, where would you store .ddl files? In /configs? In the same directory as the go database code that uses it?

The directories starting with . or _ are not ignored by Go. At least I tried importing exported symbols from those packages and it totally works and builds

Not sure what do you mean by the phrase:

Note that Go will also ignore directories or files that begin with "." or "_", so you have more flexibility in terms of how you name your test data directory

I'd like to contribute a Traditional Chinese (zh-TW) version of the README.

Thank you for this project. GitHub has just shipped a new feature that allows to mark a repository as a template for new repositories. Setting it up should take just a minute, but it's not something other developers can do via Pull Requests: it requires admin privileges.

Here's how to do it: https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/

The first thing you will run into when using go.mod, putting code outside GOPATH, and using the recommended folder structure is that your cmd/ does not have access to your internal or pkg folder. Therefore you are automatically required to resort to using the require/replace fix to actually get access to the code or actually split your code into actual modules and upload separately.

While the require/replace fix works and builds, your IDE will probably still have problems picking up the imports for good code navigation unless you manually update your go.mod file in the pkg or internal folder. (you cant use go build to update your go.mod/sum file as there is nothing to build in the folder) Of course, this is more of an IDE problem.

module some-api

replace some-pkg v0.0.0 => ../../pkg

require (
	some-pkg v0.0.0
)

Would people still recommend this folder layout when using go modules, have multiple cmd applications, and especially when putting code outside the gopath? I am curious as I see more and more people starting to use modules and putting their code in a GOPATH-less environment and this is for sure bound to create problems and confusion when using modules as it requires "some" custom setup. Of course, nothing major once you figure it out.

Come to think of it, this is more of a general issue with go mod. You will run into this issue from the moment you put your main.go file in a subfolder and not the root.

Pulling out my hair to do something as simple (or in go- complex) as using dep, gb and make to perform a simple build of a repo with this structure. Even if its opinionated it would help to show

• a Makefile including gb (the refs are good but much too complex for a beginner)
• a way to use dep for installing dependencies as part of the make process

It seems common to have a "testdata" directory for additional test data. Any specific reason why it's not included in this repo?

What is a common approach when building API Server from swagger spec file (usually swagger.yml).
Command swagger generate server... generates a bunch of .go files. Where those generated .go files should be placed.
Is a good approach to put them to /pkg/api/ ?

Your comments on the use of a src/ directory aren't correct, at least in the GOPATH approach which has been the recommendation in the past:
https://golang.org/doc/gopath_code.html

Here's what happens if you don't have a src/ directory in your project:

lctl.go:3:8: cannot find package "lctlutil" in any of:
/home/dean/bin/go1.14.linux-amd64/go/src/lctlutil (from $GOROOT)
/home/dean/src/golang/integration/lctl/src/lctlutil (from $GOPATH)
/home/dean/src/golang/go3p/src/lctlutil

Go looks for a src/ directory.

Also the link in that section points to an updated page which doesn't mention the src/ directory. Apparently it has been updated for modules.

What happens if I put the frontend (SPA) inside the Web directory once I need to deploy ?

I mean, I use CI to build let's say three Docker containers, reprsenting my three microservices. With Cobra.

They are called mysoftware-collector and mysoftware-pusher and mysoftware-server.

And on another Git repository, I develop the mysoftware-frontend with Angular.

If I use the /web for the frontend Angular files. How do I deploy it ?

Thanks !

Hello,

As the title said, here is the address: https://github.com/godiscourse/godiscourse

Thanks

Where to put "web" assets like .css, .scss/.sass, .less that need build, minify and copy to "web/static"?

I've always been a big fan of go and this is my first time trying to follow a suggested structure for my project instead of just making it up.

I was trying to use the internal/app/_your_app_ structure with a go module. To achieve this I had to add the below to my go.mod file and had to add a go.mod file to the relative folder, as I wanted to import as "github.com/sc7639/network-cli-tool/internal/app/command".

require github.com/sc7639/network-cli-tool/internal/app v0.0.0

replace github.com/sc7639/network-cli-tool/internal/app => ./internal/app/network-cli/

I'm just wondering if this is how you would suggest doing it or if there is a better way I'm seeing?
Thanks in advance for any help.

Does anyone have sample of dockerfile for standard project layout for the multi stage build ?

please help

Hello,

I'm new to go and have what I think is an extremely basic question: Where are the go.mod and go.sum file or files? Edit: and a follow on question, can you provide some example of go.mod files?

Thanks

This is a common layout pattern, but it's not universally accepted and some in the Go community don't recommend it.

In the /pkg section; either state the pros/cons or link to something that expounds

del

Add readme chinese translation.

As shown below.

Standard Go Project Layout

🌍 English ∙ 简体中文

This is a basic layout for Go application projects. It's not an official standard defined by the core Go dev team; however, it is a set of common historical and emerging project layout patterns in the Go ecosystem. Some of these patterns are more popular than others. It also has a number of small enhancements along with several supporting directories common to any large enough real world application.

Go项目标准布局

🌍 English ∙ 简体中文

这是Go应用程序项目的基础布局。这不是Go核心开发团队定义的官方标准；无论是在经典项目还是在新兴的项目中，这都是Go生态系统中一组常见的项目布局模式。这其中有一些模式比另外的一些更受欢迎。它通过几个支撑目录为任何足够大规模的实际应用程序提供一些增强功能。