mauvehed.com
mauvehed's dotfiles for personal and work environments
1# Go (Golang) Usage
2
3This document provides a guide to setting up and using the Go programming language, including managing versions and common commands.
4
5## Overview
6
7[Go](https://go.dev/) (often referred to as Golang) is an open-source programming language designed by Google. It is known for its simplicity, efficiency, strong support for concurrency, and robust standard library.
8
9## Installation
10
11There are several ways to install Go:
12
13* **Official Installers**: Download from [go.dev/dl/](https://go.dev/dl/).
14* **Homebrew (macOS)**:
15 ```sh
16 brew install go
17 ```
18 This usually installs the latest stable version.
19* **Go Version Manager (`goenv`)** (Recommended for managing multiple Go versions):
20 [goenv](https://github.com/syndbg/goenv) lets you easily switch between multiple versions of Go. It's similar to `pyenv` for Python or `tfenv` for Terraform.
21
22 **Installation of `goenv` (macOS with Homebrew):**
23 ```sh
24 brew install goenv
25 ```
26 For other systems or manual install, see the [goenv installation guide](https://github.com/syndbg/goenv#installation).
27
28 **Using `goenv`:**
29 1. Initialize `goenv` in your shell (add to `.zshrc` or `.bashrc`, managed by `chezmoi`):
30 ```sh
31 # Example for .zshrc
32 # if command -v goenv 1>/dev/null 2>&1; then
33 # eval "$(goenv init -)"
34 # fi
35 ```
36 2. List available Go versions to install:
37 ```sh
38 goenv install -l
39 ```
40 3. Install a specific Go version:
41 ```sh
42 goenv install <version>
43 # Example: goenv install 1.18.3
44 ```
45 4. Set global or local (per-project) Go version:
46 ```sh
47 goenv global <version> # Sets the default Go version
48 goenv local <version> # Creates a .go-version file in the current directory
49 ```
50
51If `chezmoi` manages your Go installation, it will handle the chosen installation method.
52
53## Environment Variables
54
55Go uses several environment variables to configure its behavior:
56
57* **`GOROOT`**: The root of your Go installation (e.g., `/usr/local/go` or a path managed by `goenv`). Usually set automatically.
58* **`GOPATH`**: Defines the root of your workspace. Before Go Modules, it was crucial for organizing Go code and compiled binaries. With Go Modules, its role has diminished but it still defines a default location for `go install` outside a module (`$HOME/go` by default).
59* **`GOBIN`**: The directory where `go install` will place compiled binaries (if set). If not set, binaries are placed in `$GOPATH/bin` (or `$HOME/go/bin`).
60* **`GO111MODULE`**: Controls Go Modules behavior.
61 * `on`: Forces module-aware mode (default in Go 1.16+).
62 * `auto`: Enables module mode if a `go.mod` file is present in the current or any parent directory.
63 * `off`: Disables module mode, uses `GOPATH` mode.
64
65These are typically set in your shell profile (`.zshrc`, `.bash_profile`), managed by `chezmoi`.
66
67## Basic Go Commands
68
69* **`go version`**: Displays the current Go version.
70 ```sh
71 go version
72 ```
73
74* **`go run <filename.go>`**: Compiles and runs a Go program.
75 ```sh
76 go run main.go
77 ```
78
79* **`go build [packages]`**: Compiles packages and their dependencies. Creates an executable in the current directory (for `main` packages).
80 ```sh
81 go build
82 go build ./cmd/myprogram
83 ```
84
85* **`go install [packages]`**: Compiles and installs packages. Executables are placed in `$GOBIN` or `$GOPATH/bin`.
86 ```sh
87 go install github.com/user/project/cmd/mytool@latest
88 ```
89
90* **`go test [packages]`**: Runs tests for the specified packages.
91 ```sh
92 go test ./...
93 go test -v ./mypackage
94 ```
95
96* **`go get [packages]`**: (Legacy behavior with Go Modules) Adds dependencies to `go.mod` and installs them. For installing tools, prefer `go install tool@version`.
97
98## Go Modules
99
100Go Modules are used for dependency management.
101
102* **`go mod init <module_path>`**: Initializes a new module in the current directory, creating a `go.mod` file.
103 ```sh
104 go mod init github.com/myuser/myproject
105 ```
106
107* **`go mod tidy`**: Adds missing and removes unused modules from `go.mod` and `go.sum`.
108 ```sh
109 go mod tidy
110 ```
111
112* **`go mod download`**: Downloads modules to the local cache.
113 ```sh
114 go mod download
115 ```
116
117* **`go list -m all`**: Lists all modules used in the current project.
118
119## Common Go Tools
120
121* **`gofmt`**: Formats Go programs.
122 ```sh
123 gofmt -w main.go # Formats and writes back to file
124 ```
125* **`goimports`**: Updates your Go import lines, adding missing and removing unreferenced ones (superset of `gofmt`). Install with `go install golang.org/x/tools/cmd/goimports@latest`.
126* **`golint` / `staticcheck` / `golangci-lint`**: Linters for Go code. `golangci-lint` is a popular meta-linter.
127
128## Resources
129
130* **Official Go Website**: [https://go.dev/](https://go.dev/)
131* **Go Documentation**: [https://go.dev/doc/](https://go.dev/doc/)
132* **Effective Go (Best Practices)**: [https://go.dev/doc/effective_go](https://go.dev/doc/effective_go)
133* **Go Modules Reference**: [https://go.dev/ref/mod](https://go.dev/ref/mod)
134* **`goenv` GitHub Repository**: [https://github.com/syndbg/goenv](https://github.com/syndbg/goenv)
135* **Go Playground**: [https://go.dev/play/](https://go.dev/play/)
136
137This document provides a starting point for working with Go. Refer to the official documentation for more in-depth information.