gazeall
v0.13.13
Published
Gazeall - The all seeing file watcher and command executor.
Downloads
32
Maintainers
Readme
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).
- Watch file for changes and run things
- Install
- Usage
- Improved execution output
- CLI Examples
- Run NPM scripts
- 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:
- Commands being executed
- Files being watched when verbose mode enables (see options above).
- Process output with process id and command shown in square brackets.
- Process output after the "=>" arrow.
- 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.
- Make sure to place commands inside quotes if options are passed or there are multiple commands.
- 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