README.md

Gazeall - Run command on folder and file changes

This project was developed using the help of DevMentor Project Creator Tools: DM-Tools (Spins up projects quickly, stop making them by hand).

1. Watch file for changes and run things
2. Install
3. Usage
4. Improved execution output
5. CLI Examples
   1. Run programs and commands using the CLI
   2. Watch all files and sub-folders
   3. Watch all files under multiple sub-folders
   4. Omitting watch folders and files
      1. Watch option
   5. Delay running a command
   6. Wait first and run command on change
   7. Target specific files to watch
   8. Running multiple commands
6. Run NPM scripts
   1. NPM script examples
   2. Run NPM scripts in sequence
   3. Run NPM scripts in parallel
7. Diagnosing EADDRESSINUSE

Watch file for changes and run things

Gazeall watches files and folders for changes, then leaps to action and executes one of more commands.

Gazeall works both as a CLI tool and equally well running NPM scripts from "package.json".

NPM scripts can be run in parallel or synchronous mode.

Install

Install in your Node.js project.

npm install gazeall

Install globally to use as a command in other scripts.

npm install -g gazeall

Usage

$ gazeall -h
Usage: gazeall [options] [files...]

Options:
  -v, --version           output the version number
  -r, --run <command...>  run commands then wait for changes to re-run
  -w, --watch <files...>  files to watch for change
  -W, --wait              enter wait, commands will run on changes
  -p, --npmp <scripts>    NPM scripts to run parallel
  -s, --npms <scripts>    NPM scripts to run synchronous
  -d, --delay <ms>        start delay value in milliseconds
  -H, --halt              halt on error
  -V, --verbose           verbose logging
  -h, --help              display help for command

Improved execution output

Default logging, with command.

Verbose logging, with process id, command, watch files.

Logging with prefix, "=>" is what gazeall is doing. Logging in white, is output from executed command, process, or NPM script.

Output now shows the following:

1. Commands being executed
2. Files being watched when verbose mode enables (see options above).
3. Process output with process id and command shown in square brackets.
4. Process output after the "=>" arrow.
5. Process execution time.

Improved output is more useful when multiple processes are executing.

CLI Examples

The examples below show various ways to run gazeall from the command line.

1. Make sure to place commands inside quotes if options are passed or there are multiple commands.
2. When using globs to recuse into sub-folders, make sure to put them inside quotes.

Run programs and commands using the CLI

To run a JavaScript file using Node.js and have gazeall monitor all JavaScript file for changes in the current folder and all sub-folders, type the following.

npx gazeall main.js

The above syntax is just shorthand for:

npx gazeall --run "node main.js" --watch "**/*.js"

The following shorthand will run a JavaScript file using Node:

npx gazeall main.js src bin

is equivalent to:

npx gazeall --run "node main.js" --watch "src/*" "bin/*"

Watch all files and sub-folders

Watch all files under "src" folder.

npx gazeall --run  <command> "src/*"

NOTE: For file globs, always put then inside quotes.

Watch all files under "src" folder and sub-folders.

npx gazeall --run <command> "src/**/*"

Watch all files under multiple folders recursively.

NOTE: Files are space separated and quoted and always appear last.

Watch all files under multiple sub-folders

This will run the command and then start to watch files for changes under sub-folder "src" and "libs".

npx gazeall --run <command> "folder1/**/*" "folder2/**/*"

npx gazeall --run "node src/main.js" --watch "src/**/*" "libs/**/*"

Omitting watch folders and files

This shorthand will watch all files under all sub-folders "**/*".

npx gazeall --run "node src/main.js"

Expands to:

npx gazeall --run "node src/main.js" --watch "**/*"

Watch option

The watch flag is optional. Should you get confused about usage, it may be added to improve clarity.

npx gazeall -r <command> -w "src/**/*" "test/**/*"

npx gazeall --run <command> --watch "src/**/*" "test/**/*"

Delay running a command

To delay running a command, make use of the "--delay <milliseconds>" flag. This will delay the execution of the command by 5 seconds.

npx gazeall --run "node src/main.js" --delay 5000

Wait first and run command on change

Gazeall executes the command immediately. However you can tell it to wait for changes before executing the command.

Below command is only executed after changes are detected when the "--wait" flag is used.

npx gazeall --wait --run "node src/main.js"

Target specific files to watch

Files are separated by a space.

npx gazeall --run "node src/main.js" --watch index.html src/main.js

Running multiple commands

Multiple commands can be executed. Each command and its arguments must be surrounded with quotes.

npx gazeall --run "tsc src/*.ts" "node build/main.js" --watch "src/*" "build/*"

Run NPM scripts

If your Node.js project has a "package.json" file, and gazeall is run without any arguments. It will look for the property in "main" and run the file using Node. If the "main" property is missing gazeall will exist with an error message.

// File: package.json
{
  ...
  "main": "server.js",
  "scripts": {
    "start": "gazeall"
  },
  ...
}

The same execution logic will be used if you also type, "npx gazeall" in the Terminal from the root folder of the project.

So typing just "npx gazeall" from the root of the Node project would be similar to:

npx gazeall --run "node server.js --watch "**/*.js"

NPM script examples

For running NPM scripts inside package.json, gazeall can run NPM scripts either in parallel or synchronous.

• To run in parallel mode, use: "--npmp".
• To run in synchronous mode, use: "--npms".

NOTE: You may also use the "--wait" switch when running NPM scripts.

The syntax format is:

gazeall --npmp "scripts..." "watch folders and files"
gazeall --npms "scripts..." "watch folders and files"

Run NPM scripts in sequence

In sequence mode, gazeall will wait for the running command to complete before running the next command.

Here three NPM scripts are run in sequence (build->webinit->webrefresh). The next NPM script is run only after the current NPM script completes.

  "scripts": {
    "webwatch": "gazeall --npms 'build webinit webrefresh' 'src/**/*'"
  }

NOTE: You can used single quotes inside the double quotes for grouping. This was you won't have to escape double quotes.

This NPM script "build", runs and gazeall watches two folders and their sub-folders.

  "scripts": {
    "build": "gazeall --npms build 'src/**/*' 'vendor/**/*'"
  }

Run NPM scripts in parallel

In gazeall parallel mode, all NPM scripts execute one after the other without waiting.

  "scripts": {
    "build": "gazeall --npmp 'run:dev run:test' 'src/**/*'"
  }

gazeall runs NPM scripts and watches two folders and their sub-folders.

  "scripts": {
    "build": "gazeall --npmp 'run:dev run:test' 'src/**/*' 'test/**/*'"
  }

NOTE: We make use of double quote and need to escape them, this is the best practice as single quotes can have problem when used on Windows.

Diagnosing EADDRESSINUSE

Although code has been add to perform process clean up with Gazeall is stopped, there are time when a process is left running. When you run a process using Gazeall you might be presented with an the following error message:

Error: listen EADDRINUSE: address already in use

This can be easily cleaned up manually, figure out what address and or port is in use. Next use "lsof" to list process with open file descriptors. User the "-i" flag to filter on an interface and port.

The following will list processes with an interface opened listening on port 3000.

lsof -i :3000

Then we can make use of the "kill -9" to forcefully terminate the process.

Pass the Process Id when terminating it. Make sure you have the correct process.

kill -9 11049