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