The Go source file (.go)

The basics

What is a Go file?

Anatomy

What's inside a Go file

Every Go file has the same shape: a package clause, then imports, then declarations of types, variables, constants and functions in any order. Here is a small command-line program, part by part.

// Command greet prints a greeting for each name given.
package main

import (
	"errors"
	"flag"
	"fmt"
	"os"
	"strings"
)

var shout = flag.Bool("shout", false, "print in capitals")

type greeter struct {
	greeting string
}

func (g greeter) greet(name string) (string, error) {
	if name == "" {
		return "", errors.New("empty name")
	}
	msg := g.greeting + ", " + name + "!"
	if *shout {
		msg = strings.ToUpper(msg)
	}
	return msg, nil
}

func main() {
	flag.Parse()
	g := greeter{greeting: "Hello"}
	for _, name := range flag.Args() {
		msg, err := g.greet(name)
		if err != nil {
			fmt.Fprintln(os.Stderr, err)
			os.Exit(1)
		}
		fmt.Println(msg)
	}
}

1. 1// Command greet prints …

   A doc comment

   A comment directly above a declaration documents it; go doc and pkg.go.dev show it. Above package main, it describes the whole program.

2. 2package main

   The package clause

   Always the first statement. Every .go file in a folder must name the same package. main is special: together with a func main, it makes an executable program. Any other name makes a library.

3. 3import ( "errors" … )

   Imports

   Packages this file uses, from the standard library here. An import that isn't used is a compile error, not a warning; goimports and editors add and remove them for you.

4. 4var shout = flag.Bool("shout", …)

   A package-level variable

   Declared outside any function and visible in every file of the package. This one defines a -shout command-line flag.

5. 5type greeter struct { greeting string }

   A struct type

   Go has no classes: types are structs, and behaviour comes from methods. Lower-case names are private to the package; capitalised names are exported.

6. 6func (g greeter) greet(name string) (string, error)

   A method with two results

   (g greeter) is the receiver: it attaches greet to the type. Functions can return several values, and a function that can fail returns an error last.

7. 7errors.New("empty name")

   An error value

   Go has no exceptions for ordinary failures. Errors are values that the caller checks, usually with if err != nil.

8. 8msg := g.greeting + …

   A short variable declaration

   := declares a variable and infers its type from the value. A variable that's declared and never used is a compile error.

9. 9for _, name := range flag.Args()

   A range loop

   for is Go's only loop. range gives the index and the value; _, the blank identifier, discards the index.

10. 10os.Exit(1)

    The exit status

    Ends the program with status 1, failure. Returning from main normally means 0, success.

11. 11 if err != nil {

    gofmt's layout

    Tabs for indentation and the opening brace on the same line. The brace isn't style: Go inserts semicolons at line ends, so a brace on its own line is a syntax error.

Under the hood

How to run and build a Go file

Projects

Packages, modules and the go.mod file

# start a module in an empty folder
go mod init example.com/greet

# go.mod, for example:
module example.com/greet

go 1.24

require example.com/othermodule v1.2.3

# everyday commands
go run .              # compile and run the package in this folder
go build              # make an executable: greet, or greet.exe on Windows
go test ./...         # run every _test.go file in the module
go mod tidy           # add missing requirements, remove unused ones

Conventions

File names, build constraints and gofmt

Testing

_test.go files and go test

Versions

Go versions and the compatibility promise

Related formats

Go compared with C, Rust, Java and Python files

Troubleshooting

Go errors people hit most, and what they mean

How to

How to open and edit a Go file, and is it safe?

Free downloads

Sample Go files to download

Free sample Go files for testing editors, syntax highlighting, code viewers, CI and upload filters. Each one is gofmt-formatted, passes go vet and runs; the tests pass with go test. They need Go 1.21 or later, and Go 1.24 or later for the benchmark.

Loading…

What's inside sample-program.go

The file is commented: open it in a text editor and each numbered comment marks one of these parts. Run it with go run sample-program.go to see a stock report.

1. Comments 1 and 2: the package clause and imports

   package main, which makes a program, and five standard library packages, each of which must be used.

2. Comments 3 to 5: a constant, a struct and a method

   A package-level constant, an item struct with unexported fields, and a value method attached to it.

3. Comment 6: an interface, satisfied implicitly

   A String method makes item a fmt.Stringer without declaring it, so fmt.Println prints items with it.

4. Comment 7: errors as values

   find returns an item and an error, wrapping a sentinel error with %w so callers can test it with errors.Is.

5. Comments 8 and 9: slices and sorting

   A slice of fictional shop items, sorted largest value first with slices.SortFunc and cmp.Compare.

6. Comments 10 and 11: goroutines and defer

   One goroutine per item, a sync.WaitGroup to wait for them and a mutex around the shared total; defer wg.Done() runs when each goroutine finishes.

7. Comment 12: checking errors

   One lookup that succeeds and one that fails, recognised with errors.Is.

All sample Go files

• Commented sample program

  sample-program.go · 3.0 KB (3,076 bytes)

  A complete program that prints a sorted stock report: a struct with methods, an implicit interface, error values, slices, sorting, goroutines with a WaitGroup and mutex, and defer, with numbered comments explaining each part.

  • Checking editors, linters and syntax highlighters on Go
  • Teaching the parts of a Go program
  DownloadOpen

• Hello world

  sample-hello.go · 214 bytes

  The classic first Go program: package main, one import and func main.

  • A minimal build test
  • Checking a new Go installation
  DownloadOpen

• Word counter with Unicode text

  sample-wordcount.go · 1.8 KB (1,887 bytes)

  Counts words in English, French, German and Japanese text with unicode.IsLetter, and prints each word's length in bytes and in runes (characters).

  • Encoding tests with non-ASCII string literals
  • The code that `sample-wordcount_test.go` tests
  DownloadOpen

• Test file (_test.go)

  sample-wordcount_test.go · 2.1 KB (2,165 bytes)

  Tests for sample-wordcount.go: a table-driven test with subtests and Unicode cases, a tie-breaking test, an Example function with checked output and a benchmark. Run with go test -v sample-wordcount.go sample-wordcount_test.go.

  • Checking CI runs and reports Go tests
  • Testing tools that treat `_test.go` files specially
  DownloadOpen

• Build constraint (//go:build unix)

  sample-unix.go · 1.4 KB (1,473 bytes)

  Prints the open-file limits with syscall.Getrlimit, which Windows doesn't have, so the file carries //go:build unix. In a module, GOOS=windows go build . reports "build constraints exclude all Go files".

  • Testing how tools handle build constraints
  • Cross-compilation checks in CI
  DownloadOpen

• 100 KB Go file

  sample-100kb.go · 100 KB (102,400 bytes)

  A table of the first 13,860 prime numbers and a program that checks every one, padded with a comment to exactly 102,400 bytes. gofmt-clean and runs.

  • Upload and size-limit tests
  • Editor, highlighter and compile-time benchmarks
  DownloadOpen

Ways to test with them

• CI checks: gofmt -l on the samples should list nothing, and go vet and go run should pass on each file by name. Each sample is its own program with its own main, so give each one its own folder before building them as packages.
• Build constraints: build sample-unix.go in a module with GOOS=windows, GOOS=linux and GOOS=darwin to check your pipeline's cross-compilation.
• Encoding: sample-wordcount.go should print café as 5 bytes and 4 runes; anything else means the file's encoding changed on the way.
• Upload limits: sample-100kb.go is exactly 102,400 bytes, for testing a limit at the boundary.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

Go files, frequently asked