Go (Golang) Basics — Files, Commands, go.mod, go.sum, go tidy, vendor, download, Compilation & Testing

A complete beginner-friendly guide

Go is a fast, simple, and powerful language created by Google for building server-side, cloud-native, and distributed systems.

This guide gives a full beginner overview of:

✔ Go project structure
✔ Go files and packages
✔ How to run & compile Go programs
✔ How testing works
✔ What go.mod & go.sum are
✔ go mod commands: tidy, vendor, download
✔ Important Go CLI commands

---

Go Project Structure

A typical small Go project looks like this:

myproject/
│
├── go.mod
├── go.sum
├── main.go
└── utils/
      └── math.go

---

Understanding Go Files

➤ A .go file contains Go code

Every file starts with a package declaration.

Example main.go:

package main

import "fmt"

func main() {
    fmt.Println("Hello, Go!")
}

If a file has package main and func main() → it creates an executable program.

---

Go Packages

A package is simply a folder containing .go files that share the same package name.

Example:

utils/
   math.go

math.go:

package utils

func Add(a, b int) int {
    return a + b
}

Import in main:

import "myproject/utils"

---

Go Modules (go.mod)

Modules are Go’s dependency & versioning system.

Create a module using:

go mod init myproject

This generates:

module myproject

go 1.22

go.mod contains:

• Module path

• Go version

• Required dependencies

• Replace rules (optional)

Example:

module github.com/vinod/myapp

go 1.22

require github.com/gin-gonic/gin v1.9.1

---

go.sum (Dependency Checksums)

go.sum stores cryptographic checksums of all dependencies.

Purpose:

✔ Security — Ensures dependencies weren't modified
✔ Reproducible builds — Ensures same version works everywhere
✔ Integrity verification

Example:

github.com/gin-gonic/gin v1.9.1 h1:Xu.../checksum
github.com/gin-gonic/gin v1.9.1/go.mod h1:Qw.../checksum

Go verifies these every time modules are downloaded.

---

Go Commands for Files & Executables

Run a Go program:

go run main.go

Run entire module:

go run .

Build a binary:

go build

Build with output name:

go build -o myapp

---

Go Tests (_test.go)

Go has a built-in testing library.

Naming rules:

• File ends with _test.go

• Function format: TestXxx(t *testing.T)

Example:

func TestAdd(t *testing.T) {
    got := Add(2, 3)
    want := 5

    if got != want {
        t.Errorf("got %d, want %d", got, want)
    }
}

Run tests:

go test ./...

Verbose:

go test -v

---

Important go.mod Commands

(These are essential for real projects)

---

✔ go mod tidy

Cleans & fixes dependencies.

Does:

• Add missing dependencies based on imports

• Remove unused dependencies

• Update go.sum

• Keep your module graph correct

Command:

go mod tidy

Use it after:

• Adding imports

• Removing imports

• Before committing code

---

✔ go mod vendor

Creates a vendor/ folder with copies of all dependencies.

vendor/
  ├── github.com/pkg/errors/
  ├── golang.org/x/net/

Purpose:

✔ Offline builds
✔ Reproducible CI builds
✔ Enterprise environments with blocked internet

Command:

go mod vendor

To compile using vendor folder:

go build -mod=vendor

---

✔ go mod download

Downloads all dependencies into Go’s module cache:

$GOPATH/pkg/mod

Command:

go mod download

Use cases:

• For CI/CD systems

• For Docker builds

• For warming cache

• When preparing offline builds

You can download specific modules:

go mod download github.com/gin-gonic/gin

---

✔ go mod verify

Verifies checksums in go.sum.

go mod verify

Ensures no dependency code was tampered with.

---

go get (Add/Upgrade Dependencies)

Add new dependency:

go get github.com/pkg/errors

Upgrade dependency:

go get -u github.com/pkg/errors

Remove dependency (indirectly):

go mod tidy

---

Go Build Modes

Cross-compile for Linux:

GOOS=linux GOARCH=amd64 go build

Cross-compile for macOS ARM:

GOOS=darwin GOARCH=arm64 go build

Cross-compile for Windows:

GOOS=windows GOARCH=amd64 go build -o app.exe

Go supports cross-compilation without extra tools.

---

Summary Table

Feature / Command	Purpose
go.mod	Lists module name + dependencies
go.sum	Stores dependency checksums
go run	Build + run app
go build	Compile binary
go test	Run tests
go mod tidy	Add missing + remove unused deps
go mod vendor	Copy dependencies into vendor/
go mod download	Download all required deps
go fmt	Format code
go get	Add/upgrade dependency

---

Final Text Diagram: Go Project Workflow

Write Go code (.go files)
        │
        ▼
Initialize module
   go mod init
        │
        ▼
Add imports → dependencies appear in go.mod
        │
        ▼
Clean module
   go mod tidy
        │
        ▼
Download deps
   go mod download
        │
        ▼
(Optional) create vendor folder
   go mod vendor
        │
        ▼
Build or run
   go build
   go run
        │
        ▼
Write tests → go test