github.com/zhb127/air@v0.0.2-0.20231109030911-fb911e430cdd/README.md (about) 1 # :cloud: Air - Live reload for Go apps 2 3 [![Go](https://github.com/cosmtrek/air/actions/workflows/release.yml/badge.svg)](https://github.com/cosmtrek/air/actions?query=workflow%3AGo+branch%3Amaster) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/dcb95264cc504cad9c2a3d8b0795a7f8)](https://www.codacy.com/gh/cosmtrek/air/dashboard?utm_source=github.com&utm_medium=referral&utm_content=cosmtrek/air&utm_campaign=Badge_Grade) [![Go Report Card](https://goreportcard.com/badge/github.com/cosmtrek/air)](https://goreportcard.com/report/github.com/cosmtrek/air) [![codecov](https://codecov.io/gh/cosmtrek/air/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmtrek/air) 4 5 ![air](docs/air.png) 6 7 English | [简体中文](README-zh_cn.md) | [繁體中文](README-zh_tw.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 ### Overwrite specify configuration from arguments 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 ### Via `go install` (Recommended) 44 45 With go 1.18 or higher: 46 47 ```bash 48 go install github.com/cosmtrek/air@latest 49 ``` 50 51 ### Via install.sh 52 53 ```bash 54 # binary will be $(go env GOPATH)/bin/air 55 curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin 56 57 # or install it into ./bin/ 58 curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s 59 60 air -v 61 ``` 62 63 ### Via [goblin.run](https://goblin.run) 64 65 ```sh 66 # binary will be /usr/local/bin/air 67 curl -sSfL https://goblin.run/github.com/cosmtrek/air | sh 68 69 # to put to a custom path 70 curl -sSfL https://goblin.run/github.com/cosmtrek/air | PREFIX=/tmp sh 71 ``` 72 73 ### Docker/Podman 74 75 Please pull this docker image [cosmtrek/air](https://hub.docker.com/r/cosmtrek/air). 76 77 ```bash 78 docker/podman run -it --rm \ 79 -w "<PROJECT>" \ 80 -e "air_wd=<PROJECT>" \ 81 -v $(pwd):<PROJECT> \ 82 -p <PORT>:<APP SERVER PORT> \ 83 cosmtrek/air 84 -c <CONF> 85 ``` 86 87 #### Docker/Podman .${SHELL}rc 88 89 if you want to use air continuously like a normal app, you can create a function in your ${SHELL}rc (bash,zsh,etc...) 90 91 ```bash 92 air() { 93 podman/docker run -it --rm \ 94 -w "$PWD" -v "$PWD":"$PWD" \ 95 -p "$AIR_PORT":"$AIR_PORT" \ 96 docker.io/cosmtrek/air "$@" 97 } 98 ``` 99 100 `<PROJECT>` is your project path in container, eg: /go/example 101 if you want to enter the container, Please add --entrypoint=bash. 102 103 <details> 104 <summary>For example</summary> 105 106 One of my project runs in docker: 107 108 ```bash 109 docker run -it --rm \ 110 -w "/go/src/github.com/cosmtrek/hub" \ 111 -v $(pwd):/go/src/github.com/cosmtrek/hub \ 112 -p 9090:9090 \ 113 cosmtrek/air 114 ``` 115 116 Another example: 117 118 ```bash 119 cd /go/src/github.com/cosmtrek/hub 120 AIR_PORT=8080 air -c "config.toml" 121 ``` 122 123 this will replace `$PWD` with the current directory, `$AIR_PORT` is the port where to publish and `$@` is to accept arguments of the aplication itself for example -c 124 125 </details> 126 127 ## Usage 128 129 For less typing, you could add `alias air='~/.air'` to your `.bashrc` or `.zshrc`. 130 131 First enter into your project 132 133 ```bash 134 cd /path/to/your_project 135 ``` 136 137 The simplest usage is run 138 139 ```bash 140 # firstly find `.air.toml` in current directory, if not found, use defaults 141 air -c .air.toml 142 ``` 143 144 You can initialize the `.air.toml` configuration file to the current directory with the default settings running the following command. 145 146 ```bash 147 air init 148 ``` 149 150 After this, you can just run the `air` command without additional arguments and it will use the `.air.toml` file for configuration. 151 152 ```bash 153 air 154 ``` 155 156 For modifying the configuration refer to the [air_example.toml](air_example.toml) file. 157 158 ### Runtime arguments 159 160 You can pass arguments for running the built binary by adding them after the air command. 161 162 ```bash 163 # Will run ./tmp/main bench 164 air bench 165 166 # Will run ./tmp/main server --port 8080 167 air server --port 8080 168 ``` 169 170 You can separate the arguments passed for the air command and the built binary with `--` argument. 171 172 ```bash 173 # Will run ./tmp/main -h 174 air -- -h 175 176 # Will run air with custom config and pass -h argument to the built binary 177 air -c .air.toml -- -h 178 ``` 179 180 ### Docker-compose 181 182 ```yaml 183 services: 184 my-project-with-air: 185 image: cosmtrek/air 186 # working_dir value has to be the same of mapped volume 187 working_dir: /project-package 188 ports: 189 - <any>:<any> 190 environment: 191 - ENV_A=${ENV_A} 192 - ENV_B=${ENV_B} 193 - ENV_C=${ENV_C} 194 volumes: 195 - ./project-relative-path/:/project-package/ 196 ``` 197 198 ### Debug 199 200 `air -d` prints all logs. 201 202 ## Installation and Usage for Docker users who don't want to use air image 203 204 `Dockerfile` 205 206 ```Dockerfile 207 # Choose whatever you want, version >= 1.16 208 FROM golang:1.21-alpine 209 210 WORKDIR /app 211 212 RUN go install github.com/cosmtrek/air@latest 213 214 COPY go.mod go.sum ./ 215 RUN go mod download 216 217 CMD ["air", "-c", ".air.toml"] 218 ``` 219 220 `docker-compose.yaml` 221 222 ```yaml 223 version: "3.8" 224 services: 225 web: 226 build: 227 context: . 228 # Correct the path to your Dockerfile 229 dockerfile: Dockerfile 230 ports: 231 - 8080:3000 232 # Important to bind/mount your codebase dir to /app dir for live reload 233 volumes: 234 - ./:/app 235 ``` 236 237 ## Q&A 238 239 ### "command not found: air" or "No such file or directory" 240 241 ```zsh 242 export GOPATH=$HOME/xxxxx 243 export PATH=$PATH:$GOROOT/bin:$GOPATH/bin 244 export PATH=$PATH:$(go env GOPATH)/bin <---- Confirm this line in you profile!!! 245 ``` 246 247 ### Error under wsl when ' is included in the bin 248 249 Should use `\` to escape the `' in the bin. related issue: [#305](https://github.com/cosmtrek/air/issues/305) 250 251 ### Question: how to do hot compile only and do not run anything? 252 253 [#365](https://github.com/cosmtrek/air/issues/365) 254 255 ```toml 256 [build] 257 cmd = "/usr/bin/true" 258 ``` 259 260 ## Development 261 262 Please note that it requires Go 1.16+ since I use `go mod` to manage dependencies. 263 264 ```bash 265 # Fork this project 266 267 # Clone it 268 mkdir -p $GOPATH/src/github.com/cosmtrek 269 cd $GOPATH/src/github.com/cosmtrek 270 git clone git@github.com:<YOUR USERNAME>/air.git 271 272 # Install dependencies 273 cd air 274 make ci 275 276 # Explore it and happy hacking! 277 make install 278 ``` 279 280 Pull requests are welcome. 281 282 ### Release 283 284 ```bash 285 # Checkout to master 286 git checkout master 287 288 # Add the version that needs to be released 289 git tag v1.xx.x 290 291 # Push to remote 292 git push origin v1.xx.x 293 294 # The CI will process and release a new version. Wait about 5 min, and you can fetch the latest version 295 ``` 296 297 ## Star History 298 299 [![Star History Chart](https://api.star-history.com/svg?repos=cosmtrek/air&type=Date)](https://star-history.com/#cosmtrek/air&Date) 300 301 ## Sponsor 302 303 [![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/default-orange.png)](https://www.buymeacoffee.com/cosmtrek) 304 305 Give huge thanks to lots of supporters. I've always been remembering your kindness. 306 307 ## License 308 309 [GNU General Public License v3.0](LICENSE)