github.com/fairyhunter13/air@v1.40.5/README.md (about) 1 # Air [![Go](https://github.com/fairyhunter13/air/workflows/Go/badge.svg)](https://github.com/fairyhunter13/air/actions?query=workflow%3AGo+branch%3Amaster) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/dcb95264cc504cad9c2a3d8b0795a7f8)](https://www.codacy.com/gh/fairyhunter13/air/dashboard?utm_source=github.com&utm_medium=referral&utm_content=fairyhunter13/air&utm_campaign=Badge_Grade) [![Go Report Card](https://goreportcard.com/badge/github.com/fairyhunter13/air)](https://goreportcard.com/report/github.com/fairyhunter13/air) [![codecov](https://codecov.io/gh/fairyhunter13/air/branch/master/graph/badge.svg)](https://codecov.io/gh/fairyhunter13/air) 2 3 :cloud: Live reload for Go apps 4 5 ![air](docs/air.png) 6 7 English | [简体中文](README-zh_cn.md) 8 9 ## Motivation 10 11 When I get started with developing websites in Go and [gin](https://github.com/gin-gonic/gin) framework, it's a pity 12 that gin lacks live-reloading function. In fact, I tried [fresh](https://github.com/pilu/fresh) and it seems not much 13 flexible, so I intended to rewrite it in a better way. 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 Go applications in development. Just `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 ary 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 just want to config build command and run command, you can use like following command without 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/fairyhunter13/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/fairyhunter13/air/master/install.sh | sh -s 51 52 air -v 53 ``` 54 55 P.S. Great thanks mattn's [PR](https://github.com/cosmtrek/air/pull/1) for supporting Windows platform. 56 57 ### Via `go install` 58 59 With go 1.16 or higher: 60 61 ```bash 62 go install github.com/fairyhunter13/air@latest 63 ``` 64 65 ### Docker 66 67 Please pull this docker image [fairyhunter13/air](https://hub.docker.com/r/fairyhunter13/air). 68 69 ```bash 70 docker run -it --rm \ 71 -w "<PROJECT>" \ 72 -e "air_wd=<PROJECT>" \ 73 -v $(pwd):<PROJECT> \ 74 -p <PORT>:<APP SERVER PORT> \ 75 fairyhunter13/air 76 -c <CONF> 77 ``` 78 79 For example, one of my project runs in docker: 80 81 ```bash 82 docker run -it --rm \ 83 -w "/go/src/github.com/cosmtrek/hub" \ 84 -v $(pwd):/go/src/github.com/cosmtrek/hub \ 85 -p 9090:9090 \ 86 fairyhunter13/air 87 ``` 88 89 ## Usage 90 91 For less typing, you could add `alias air='~/.air'` to your `.bashrc` or `.zshrc`. 92 93 First enter into your project 94 95 ```bash 96 cd /path/to/your_project 97 ``` 98 99 The simplest usage is run 100 101 ```bash 102 # firstly find `.air.toml` in current directory, if not found, use defaults 103 air -c .air.toml 104 ``` 105 106 You can initialize the `.air.toml` configuration file to the current directory with the default settings running the following command. 107 108 ```bash 109 air init 110 ``` 111 112 After this you can just run the `air` command without additional arguments and it will use the `.air.toml` file for configuration. 113 114 ```bash 115 air 116 ``` 117 118 For modifying the configuration refer to the [air_example.toml](air_example.toml) file. 119 120 ### Runtime arguments 121 122 You can pass arguments for running the built binary by adding them after the air command. 123 124 ```bash 125 # Will run ./tmp/main bench 126 air bench 127 128 # Will run ./tmp/main server --port 8080 129 air server --port 8080 130 ``` 131 132 You can separate the arguments passed for the air command and the built binary with `--` argument. 133 134 ```bash 135 # Will run ./tmp/main -h 136 air -- -h 137 138 # Will run air with custom config and pass -h argument to the built binary 139 air -c .air.toml -- -h 140 ``` 141 142 ### Docker-compose 143 144 ``` 145 services: 146 my-project-with-air: 147 image: fairyhunter13/air 148 # working_dir value has to be the same of mapped volume 149 working_dir: /project-package 150 ports: 151 - <any>:<any> 152 environment: 153 - ENV_A=${ENV_A} 154 - ENV_B=${ENV_B} 155 - ENV_C=${ENV_C} 156 volumes: 157 - ./project-relative-path/:/project-package/ 158 ``` 159 160 ### Debug 161 162 `air -d` prints all logs. 163 164 ## Q&A 165 166 ### "command not found: air" or "No such file or directory" 167 168 ```zsh 169 export GOPATH=$HOME/xxxxx 170 export PATH=$PATH:$GOROOT/bin:$GOPATH/bin 171 export PATH=$PATH:$(go env GOPATH)/bin <---- Confirm this line in you profile!!! 172 ``` 173 174 ## Development 175 176 Please note that it requires Go 1.16+ since I use `go mod` to manage dependencies. 177 178 ```bash 179 # 1. fork this project 180 181 # 2. clone it 182 mkdir -p $GOPATH/src/github.com/cosmtrek 183 cd $GOPATH/src/github.com/cosmtrek 184 git clone git@github.com:<YOUR USERNAME>/air.git 185 186 # 3. install dependencies 187 cd air 188 make ci 189 190 # 4. explore it and happy hacking! 191 make install 192 ``` 193 194 BTW: Pull requests are welcome~ 195 196 ### Release new version 197 198 ``` 199 # 1. checkout to master 200 git checkout master 201 202 # 2. add the version that needs to be released 203 git tag v1.xx.x 204 205 # 3. push to remote 206 git push origin v1.xx.x 207 208 the ci will processing and will release new version,wait about 5 min you can fetch the new version. 209 ``` 210 211 ## Sponsor 212 213 <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> 214 215 Huge thanks to the following supporters. I've always been remembering your kindness. 216 217 * Peter Aba 218 * Apostolis Anastasiou 219 * keita koga 220 221 ## License 222 223 [GNU General Public License v3.0](LICENSE)