github.com/yang-ricky/air@v1.30.0/README.md (about) 1 # Air [](https://github.com/yang-ricky/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/yang-ricky/air) [](https://codecov.io/gh/cosmtrek/air) 2 3 :cloud: Live reload for Go apps 4 5  6 7 ## Motivation 8 9 When I get started with developing websites in Go and [gin](https://github.com/gin-gonic/gin) framework, it's a pity 10 that gin lacks live-reloading function. In fact, I tried [fresh](https://github.com/pilu/fresh) and it seems not much 11 flexible, so I intended to rewrite it in a better way. Finally, Air's born. 12 In addition, great thanks to [pilu](https://github.com/pilu), no fresh, no air :) 13 14 Air is yet another live-reloading command line utility for Go applications in development. Just `air` in your project root directory, leave it alone, 15 and focus on your code. 16 17 NOTE: This tool has nothing to do with hot-deploy for production. 18 19 ## Features 20 21 * Colorful log output 22 * Customize build or binary command 23 * Support excluding subdirectories 24 * Allow watching new directories after Air started 25 * Better building process 26 27 ## Installation 28 29 ### Prefer install.sh 30 31 ```bash 32 # binary will be $(go env GOPATH)/bin/air 33 curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin 34 35 # or install it into ./bin/ 36 curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s 37 38 air -v 39 ``` 40 41 P.S. Great thanks mattn's [PR](https://github.com/yang-ricky/air/pull/1) for supporting Windows platform. 42 43 ### Via `go install` 44 45 With go 1.16 or higher: 46 47 ```bash 48 go install github.com/yang-ricky/air@latest 49 ``` 50 51 ### Docker 52 53 Please pull this docker image [cosmtrek/air](https://hub.docker.com/r/cosmtrek/air). 54 55 ```bash 56 docker run -it --rm \ 57 -w "<PROJECT>" \ 58 -e "air_wd=<PROJECT>" \ 59 -v $(pwd):<PROJECT> \ 60 -p <PORT>:<APP SERVER PORT> \ 61 cosmtrek/air 62 -c <CONF> 63 ``` 64 65 For example, one of my project runs in docker: 66 67 ```bash 68 docker run -it --rm \ 69 -w "/go/src/github.com/cosmtrek/hub" \ 70 -v $(pwd):/go/src/github.com/cosmtrek/hub \ 71 -p 9090:9090 \ 72 cosmtrek/air 73 ``` 74 75 ## Usage 76 77 For less typing, you could add `alias air='~/.air'` to your `.bashrc` or `.zshrc`. 78 79 First enter into your project 80 81 ```bash 82 cd /path/to/your_project 83 ``` 84 85 The simplest usage is run 86 87 ```bash 88 # firstly find `.air.toml` in current directory, if not found, use defaults 89 air -c .air.toml 90 ``` 91 92 You can initialize the `.air.toml` configuration file to the current directory with the default settings running the following command. 93 94 ```bash 95 air init 96 ``` 97 98 After this you can just run the `air` command without additional arguments and it will use the `.air.toml` file for configuration. 99 100 ```bash 101 air 102 ``` 103 104 For modifying the configuration refer to the [air_example.toml](air_example.toml) file. 105 106 ### Runtime arguments 107 108 You can pass arguments for running the built binary by adding them after the air command. 109 110 ```bash 111 # Will run ./tmp/main bench 112 air bench 113 114 # Will run ./tmp/main server --port 8080 115 air server --port 8080 116 ``` 117 118 You can separate the arguments passed for the air command and the built binary with `--` argument. 119 120 ```bash 121 # Will run ./tmp/main -h 122 air -- -h 123 124 # Will run air with custom config and pass -h argument to the built binary 125 air -c .air.toml -- -h 126 ``` 127 128 ### Docker-compose 129 130 ``` 131 services: 132 my-project-with-air: 133 image: cosmtrek/air 134 # working_dir value has to be the same of mapped volume 135 working_dir: /project-package 136 ports: 137 - <any>:<any> 138 environment: 139 - ENV_A=${ENV_A} 140 - ENV_B=${ENV_B} 141 - ENV_C=${ENV_C} 142 volumes: 143 - ./project-relative-path/:/project-package/ 144 ``` 145 146 ### Debug 147 148 `air -d` prints all logs. 149 150 ## Q&A 151 152 ### "command not found: air" or "No such file or directory" 153 154 ```zsh 155 export GOPATH=$HOME/xxxxx 156 export PATH=$PATH:$GOROOT/bin:$GOPATH/bin 157 export PATH=$PATH:$(go env GOPATH)/bin <---- Confirm this line in you profile!!! 158 ``` 159 160 ## Development 161 162 Please note that it requires Go 1.16+ since I use `go mod` to manage dependencies. 163 164 ```bash 165 # 1. fork this project 166 167 # 2. clone it 168 mkdir -p $GOPATH/src/github.com/cosmtrek 169 cd $GOPATH/src/github.com/cosmtrek 170 git clone git@github.com:<YOUR USERNAME>/air.git 171 172 # 3. install dependencies 173 cd air 174 make ci 175 176 # 4. explore it and happy hacking! 177 make install 178 ``` 179 180 BTW: Pull requests are welcome~ 181 182 ### Release new version 183 184 ``` 185 # 1. checkout to master 186 git checkout master 187 188 # 2. add the version that needs to be released 189 git tag v1.xx.x 190 191 # 3. push to remote 192 git push origin v1.xx.x 193 194 the ci will processing and will release new version,wait about 5 min you can fetch the new version. 195 ``` 196 197 ## Sponsor 198 199 <a href="https://www.buymeacoffee.com/36lcNbW" 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> 200 201 Huge thanks to the following supporters. I've always been remembering your kindness. 202 203 * Peter Aba 204 * Apostolis Anastasiou 205 * keita koga 206 207 ## License 208 209 [GNU General Public License v3.0](LICENSE)