github.com/tonkpils/snag@v1.2.1-0.20160221223445-7f8829737a1d/README.md (about) 1 # Snag [![Build Status](https://travis-ci.org/Tonkpils/snag.svg?branch=wip)](https://travis-ci.org/Tonkpils/snag) [![Coverage Status](https://coveralls.io/repos/Tonkpils/snag/badge.svg?branch=coverage&service=github)](https://coveralls.io/github/Tonkpils/snag?branch=coverage) 2 3 An automatic build tool for all your needs 4 5 ![](http://i.imgur.com/epcicvr.gif) 6 7 ## Installation 8 9 ### Releases 10 11 You can visit the [releases](https://github.com/Tonkpils/snag/releases) section to 12 download the binary for your platform. 13 14 ## [Homebrew](http://brew.sh/) 15 16 We've got a formula in homebrew! 17 18 ```bash 19 brew update && brew install snag 20 ``` 21 22 ### Source 23 24 If you have [go](http://golang.org/) installed and want to install 25 the latest and greatest you can run: 26 27 ```go 28 $ go get github.com/Tonkpils/snag 29 ``` 30 31 ## Usage 32 33 Once snag is installed, use: 34 35 ```sh 36 snag init 37 ``` 38 39 This will generate the snag file `.snag.yml`. 40 Here is a sample of the snag file: 41 42 ```yaml 43 verbose: true 44 ignore: 45 - .git 46 - "**.ext" 47 - "foo/**/bar.sh" 48 build: 49 - echo "lint code" 50 - echo "test code" 51 ``` 52 53 Snag works by reading the snag file allowing you to configure what and how 54 commands will be executed. 55 The file **must** reside in the same directory that you want to watch. 56 57 By default, snag will watch all files/folders within the current directory recursively. 58 The ignore section will tell snag to ignore any changes that happen 59 to the directories/files listed. The ignore section uses the same pattern matching 60 that [gitignore](https://www.kernel.org/pub/software/scm/git/docs/gitignore.html) uses. 61 62 The build section of the file will be executed when any file is created, deleted, or modified. 63 64 Once configured, use: 65 66 ``` 67 snag 68 ``` 69 70 From a project with a snag file and develop away! 71 72 ### Quick Use 73 74 If you find yourself working on a project that does not contain a snag file and 75 still want to use snag, you can use flags to specify commands to run. 76 77 The `-c` flag allows specifying a command just like the snag file and can 78 be defined more than once for multiple commands. The order of the commands 79 depends on the order of the flag. 80 81 ```sh 82 snag -c "echo snag world" -c "echo rocks" 83 ``` 84 85 will output 86 87 ```sh 88 |Passed | echo snag world 89 |Passed | echo rocks 90 ``` 91 92 The `-v` flag enables verbose output. It will also override the `verbose` 93 option form the snag file if it is defined to false. 94 95 **NOTE**: using the `-c` flag will skip reading a snag file even if it 96 exists in the current working directory. 97 98 ### Environment Variables 99 100 You can access your shell's environment variables by using `$$`. 101 102 ```yaml 103 build: 104 - echo $$MY_VAR 105 - rm -rf $$OUTPUT_DIR 106 ``` 107 108 ## Caveats 109 110 ### Endless build loops 111 112 Snag will run your configured commands when **ANY** file, not ignored, 113 is modifed in your current directory. 114 If your commands generate any files within the watched directory, 115 you must add them to the `ignore` section in your 116 snag file to avoid an endless build loop. 117 118 ### Trouble running shell scripts 119 120 In order to run shell scripts, your must have a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) in it. If you are trying to run a script without a 121 shebang, you will need to specify the shell it should run in. 122 123 i.e. 124 125 Running a script with a shebang 126 127 ```yaml 128 build: 129 - ./my-script 130 ``` 131 132 Running a script **without** a shebang 133 134 ```yaml 135 build: 136 - bash my-script 137 ``` 138 139 ### Ignore Pattern Matching 140 141 If you want to use asterisks in the ignore section of your snag file, 142 you need to make sure to wrap them in quotes or you may run into an 143 error like: 144 145 ``` 146 $ snag 147 2015/10/24 19:39:40 Could not parse yml file. yaml: line 6: did not find expected alphabetic or numeric character 148 ``` 149 150 ## Known Issues 151 152 * `open /dev/null: too many open files` 153 154 You may experience this error if you're running on OSX. You may need to bump 155 the maximum number of open file on your machine. You can refer to [this](http://krypted.com/mac-os-x/maximum-files-in-mac-os-x/) 156 article for more information on the max files on OSX and [this](http://superuser.com/questions/433746/is-there-a-fix-for-the-too-many-open-files-in-system-error-on-os-x-10-7-1) superuser post for a solution