diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..22d30bf --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,36 @@ +## 1.0.0 (August 17, 2016) + +First stable and documented release - however, the functionality or API has not changed from `0.0.3`. + +* __Documentation:__ Updated donation text. +* __Documentation:__ Added documentation and a changelog. + +## 0.0.7 (April 26, 2016) + +* __Patch:__ Display string-typed error properties literally, without quotes or colorization. +* __Patch:__ Removed unnecessary interpolation. + +## 0.0.6 (April 26, 2016) + +* __Patch:__ Always hide the `stack` property, as it is already handled separately. + +## 0.0.5 (April 25, 2016) + +* __Patch:__ Always hide `name` and `message` from the property listing, as these are already displayed separately anyway. +* __Patch:__ Display a more accurate error message when a stacktrace is absent - previously, it would always try to use the first line of the stacktrace. + +## 0.0.4 (April 25, 2016) + +* __Major:__ Improved error logging by displaying all properties clearly and verbosely using a custom output format, rather than just dumping the error object. + +## 0.0.3 (April 14, 2016) + +* __Patch:__ Removed stray angle bracket from Vinyl file logging output. + +## 0.0.2 (April 11, 2016) + +* __Minor:__ Clearer Vinyl file logging, by displaying relative paths when a `basePath` option is specified. + +## 0.0.1 (April 10, 2016) + +Initial release. \ No newline at end of file diff --git a/README.md b/README.md index cfa2c1f..0a93ff0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ # gulp-named-log -A logging utility, primarily intended for use with Gulp or other Vinyl streams, that outputs fancy name/severity-prefixed log lines. +A logging utility, primarily intended for use with Gulp or other Vinyl streams. Loosely inspired by `gulp-util`. Why you might want to use it: + +* Log lines are prefixed by time, name, and optionally severity. +* Errors are displayed verbosely, in such a way that all the important details are immediately obvious. +* Supports Vinyl (Gulp) streams - simply pipe through a logstream, and every affected file will be logged. + + ## License @@ -8,9 +14,9 @@ A logging utility, primarily intended for use with Gulp or other Vinyl streams, ## Donate -My income consists largely of donations for my projects. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)! +Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)! -You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. +You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you! ## Contributing @@ -22,8 +28,59 @@ Be aware that by making a pull request, you agree to release your modifications ## Usage -Example coming soon. +```javascript +var gulp = require("gulp"); +var gulpBabel = require("gulp-babel"); +var gulpCache = require("gulp-cached"); +var gulpPlumber = require("gulp-plumber"); +var gulpNamedLog = require("gulp-named-log"); + +// We define the different named loggers here. +var babelLogger = gulpNamedLog("babel"); +var gulpLogger = gulpNamedLog("gulp"); + +var source = ["src/**/*.js"] + +gulp.task('babel', function() { + return gulp.src(source) + .pipe(gulpPlumber()) + .pipe(gulpCache("babel")) + .pipe(gulpBabel({presets: ["es2015"]})) + .pipe(babelLogger.stream()) // This logs every file going through. + .pipe(gulp.dest("lib/")); +}); + +gulp.task('watch', function () { + gulpLogger.info("Watching for changes:", source); // This logs once. + gulp.watch(source, ['babel']); +}); + +gulp.task('default', ['babel', 'watch']); + +``` ## API -API documentation coming soon. \ No newline at end of file +### gulpNamedLog(name, options) + +Creates a new `gulp-named-log` instace. + +* __name:__ The name prefix that is used for each line that this logger logs. +* __options:__ + * __basePath:__ *Optional.* The root path of the project. This is used to display shorter paths when using the logger as a Vinyl stream - rather than showing the full path of the file, it will show the path relative to the project root. + * __byteLimit:__ *Defaults to `20`.* When the logger is used as a Vinyl stream, this is the maximum amount of bytes that will be rendered (in hexadecimal representation) for each file line. + +### logger.log(values...) + +Logs each of the provided values, much like `console.log` would - but with a timestamp and logger name prefixed. + +### logger.debug(values...) +### logger.info(values...) +### logger.warn(values...) +### logger.error(values...) + +Like `logger.log`, but along with a timestamp and logger name, the line will also include the specified *severity*. + +### logger.stream() + +Returns a new Vinyl stream, that will log (and pass through) every file it receives. In a typical `gulp.watch` + `gulp-cache` setup, this will only include the files that were modified (even if the result stays the same). \ No newline at end of file