github.com/connorvict/air@v0.0.0-20231005162537-279bf07db0d5/README.md (about) 1 # :cloud: Air - Live reload for Go apps 2 3 [](https://github.com/cosmtrek/air/actions?query=workflow%3AGo+branch%3Amaster) [](https://www.codacy.com/gh/cosmtrek/air/dashboard?utm_source=github.com&utm_medium=referral&utm_content=cosmtrek/air&utm_campaign=Badge_Grade) [](https://goreportcard.com/report/github.com/cosmtrek/air) [](https://codecov.io/gh/cosmtrek/air) 4 5  6 7 English | [简体中文](README-zh_cn.md) 8 9 ## Motivation 10 11 When I started developing websites in Go and using [gin](https://github.com/gin-gonic/gin) framework, it was a pity 12 that gin lacked a live-reloading function. So I searched around and tried [fresh](https://github.com/pilu/fresh), it seems not much 13 flexible, so I intended to rewrite it better. Finally, Air's born. 14 In addition, great thanks to [pilu](https://github.com/pilu), no fresh, no air :) 15 16 Air is yet another live-reloading command line utility for developing Go applications. Run `air` in your project root directory, leave it alone, 17 and focus on your code. 18 19 Note: This tool has nothing to do with hot-deploy for production. 20 21 ## Features 22 23 * Colorful log output 24 * Customize build or any command 25 * Support excluding subdirectories 26 * Allow watching new directories after Air started 27 * Better building process 28 29 ### ✨ beta feature 30 31 Support air config fields as arguments: 32 33 If you want to config build command and run command, you can use like the following command without the config file: 34 35 `air --build.cmd "go build -o bin/api cmd/run.go" --build.bin "./bin/api"` 36 37 Use a comma to separate items for arguments that take a list as input: 38 39 `air --build.cmd "go build -o bin/api cmd/run.go" --build.bin "./bin/api" --build.exclude_dir "templates,build"` 40 41 ## Installation 42 43 ### Prefer install.sh 44 45 ```bash 46 # binary will be $(go env GOPATH)/bin/air 47 curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin 48 49 # or install it into ./bin/ 50 curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s 51 52 air -v 53 ``` 54 55 ### Via `go install` 56 57 With go 1.18 or higher: 58 59 ```bash 60 go install github.com/cosmtrek/air@latest 61 ``` 62 63 ### Docker 64 65 Please pull this docker image [cosmtrek/air](https://hub.docker.com/r/cosmtrek/air). 66 67 ```bash 68 docker run -it --rm \ 69 -w "<PROJECT>" \ 70 -e "air_wd=<PROJECT>" \ 71 -v $(pwd):<PROJECT> \ 72 -p <PORT>:<APP SERVER PORT> \ 73 cosmtrek/air 74 -c <CONF> 75 ``` 76 77 <details> 78 <summary>For example</summary> 79 80 One of my project runs in docker: 81 82 ```bash 83 docker run -it --rm \ 84 -w "/go/src/github.com/cosmtrek/hub" \ 85 -v $(pwd):/go/src/github.com/cosmtrek/hub \ 86 -p 9090:9090 \ 87 cosmtrek/air 88 ``` 89 </details> 90 91 ## Usage 92 93 For less typing, you could add `alias air='~/.air'` to your `.bashrc` or `.zshrc`. 94 95 First enter into your project 96 97 ```bash 98 cd /path/to/your_project 99 ``` 100 101 The simplest usage is run 102 103 ```bash 104 # firstly find `.air.toml` in current directory, if not found, use defaults 105 air -c .air.toml 106 ``` 107 108 You can initialize the `.air.toml` configuration file to the current directory with the default settings running the following command. 109 110 ```bash 111 air init 112 ``` 113 114 After this, you can just run the `air` command without additional arguments and it will use the `.air.toml` file for configuration. 115 116 ```bash 117 air 118 ``` 119 120 For modifying the configuration refer to the [air_example.toml](air_example.toml) file. 121 122 ### Runtime arguments 123 124 You can pass arguments for running the built binary by adding them after the air command. 125 126 ```bash 127 # Will run ./tmp/main bench 128 air bench 129 130 # Will run ./tmp/main server --port 8080 131 air server --port 8080 132 ``` 133 134 You can separate the arguments passed for the air command and the built binary with `--` argument. 135 136 ```bash 137 # Will run ./tmp/main -h 138 air -- -h 139 140 # Will run air with custom config and pass -h argument to the built binary 141 air -c .air.toml -- -h 142 ``` 143 144 ### Docker-compose 145 146 ``` 147 services: 148 my-project-with-air: 149 image: cosmtrek/air 150 # working_dir value has to be the same of mapped volume 151 working_dir: /project-package 152 ports: 153 - <any>:<any> 154 environment: 155 - ENV_A=${ENV_A} 156 - ENV_B=${ENV_B} 157 - ENV_C=${ENV_C} 158 volumes: 159 - ./project-relative-path/:/project-package/ 160 ``` 161 162 ### Debug 163 164 `air -d` prints all logs. 165 166 ## Installation and Usage for Docker users who don't want to use air image 167 168 `Dockerfile` 169 ```Dockerfile 170 # Choose whatever you want, version >= 1.16 171 FROM golang:1.21-alpine 172 173 WORKDIR /app 174 175 RUN go install github.com/cosmtrek/air@latest 176 177 COPY go.mod go.sum ./ 178 RUN go mod download 179 180 CMD ["air", "-c", ".air.toml"] 181 ``` 182 183 `docker-compose.yaml` 184 ```yaml 185 version: "3.8" 186 services: 187 web: 188 build: 189 context: . 190 # Correct the path to your Dockerfile 191 dockerfile: Dockerfile 192 ports: 193 - 8080:3000 194 # Important to bind/mount your codebase dir to /app dir for live reload 195 volumes: 196 - ./:/app 197 ``` 198 199 ## Q&A 200 201 ### "command not found: air" or "No such file or directory" 202 203 ```zsh 204 export GOPATH=$HOME/xxxxx 205 export PATH=$PATH:$GOROOT/bin:$GOPATH/bin 206 export PATH=$PATH:$(go env GOPATH)/bin <---- Confirm this line in you profile!!! 207 ``` 208 209 ### Error under wsl when ' is included in the bin 210 211 Should use `\` to escape the `' in the bin. related issue: [#305](https://github.com/cosmtrek/air/issues/305) 212 213 ## Development 214 215 Please note that it requires Go 1.16+ since I use `go mod` to manage dependencies. 216 217 ```bash 218 # Fork this project 219 220 # Clone it 221 mkdir -p $GOPATH/src/github.com/cosmtrek 222 cd $GOPATH/src/github.com/cosmtrek 223 git clone git@github.com:<YOUR USERNAME>/air.git 224 225 # Install dependencies 226 cd air 227 make ci 228 229 # Explore it and happy hacking! 230 make install 231 ``` 232 233 Pull requests are welcome. 234 235 ### Release 236 237 ``` 238 # Checkout to master 239 git checkout master 240 241 # Add the version that needs to be released 242 git tag v1.xx.x 243 244 # Push to remote 245 git push origin v1.xx.x 246 247 # The CI will process and release a new version. Wait about 5 min, and you can fetch the latest version 248 ``` 249 250 ## Star History 251 252 [](https://star-history.com/#cosmtrek/air&Date) 253 254 ## Sponsor 255 256 <a href="https://www.buymeacoffee.com/cosmtrek" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" style="height: 51px !important;width: 217px !important;" ></a> 257 258 Give huge thanks to lots of supporters. I've always been remembering your kindness. 259 260 ## License 261 262 [GNU General Public License v3.0](LICENSE)