api_log.md

Grunt homepage | Documentation table of contents

The grunt API / grunt.log, grunt.verbose

Output messages to the console.

See the log lib source for more information.

The log API

Grunt output should look consistent, and maybe even pretty. As such, there is a plethora of logging methods, and a few useful patterns. All of the methods that actually log something are chainable.

Note: all methods available under grunt.verbose work exactly like grunt.log methods, but only log if the --verbose command-line option was specified.

grunt.log.write / grunt.verbose.write

Log the specified msg string, with no trailing newline.

grunt.log.write(msg)

grunt.log.writeln / grunt.verbose.writeln

Log the specified msg string, with trailing newline.

grunt.log.writeln([msg])

grunt.log.error / grunt.verbose.error

If msg string is omitted, logs ERROR in red, otherwise logs >> msg, with trailing newline.

grunt.log.error([msg])

grunt.log.ok / grunt.verbose.ok

If msg string is omitted, logs OK in green, otherwise logs >> msg, with trailing newline.

grunt.log.ok([msg])

grunt.log.subhead / grunt.verbose.subhead

Log the specified msg string in bold, with trailing newline.

grunt.log.subhead(msg)

grunt.log.writeflags / grunt.verbose.writeflags

Log a list of obj properties (good for debugging flags).

grunt.log.writeflags(obj, prefix)

grunt.log.debug / grunt.verbose.debug

Logs a debugging message, but only if the --debug command-line option was specified.

grunt.log.debug(msg)

Verbose and Notverbose

All logging methods available under grunt.verbose work exactly like their grunt.log counterparts, but only log if the --verbose command-line option was specified. There is also a "notverbose" counterpart available at both grunt.log.notverbose and grunt.log.verbose.or. In fact, the .or property can be used on both verbose and notverbose to effectively toggle between the two.

grunt.verbose / grunt.log.verbose

This object contains all methods of grunt.log but only logs if the --verbose command-line option was specified.

grunt.verbose

grunt.verbose.or / grunt.log.notverbose

This object contains all methods of grunt.log but only logs if the --verbose command-line option was not specified.

grunt.verbose.or

Utility Methods

These methods don't actually log, they just return strings that can be used in other methods.

grunt.log.wordlist

Returns a comma-separated list of arr array items.

grunt.log.wordlist(arr)

grunt.log.uncolor

Removes all color information from a string, making it suitable for testing .length or perhaps logging to a file.

grunt.log.uncolor(str)

grunt.log.wraptext

Wrap text string to width characters with \n, ensuring that words are not split in the middle unless absolutely necessary.

grunt.log.wraptext(width, text)

grunt.log.table

Wrap texts array of strings to columns widths characters wide. A wrapper for the grunt.log.wraptext method that can be used to generate output in columns.

grunt.log.table(widths, texts)

An Example

A common pattern is to only log when in --verbose mode OR if an error occurs, like so:

grunt.registerHelper('something', function(arg) {
  var result;
  var msg = 'Doing something...';
  grunt.verbose.write(msg);
  try {
    result = doSomethingThatThrowsAnExceptionOnError(arg);
    // Success!
    grunt.verbose.ok();
    return result;
  } catch(e) {
    // Something went wrong.
    grunt.verbose.or.write(msg).error().error(e.message);
    grunt.fail.warn('Something went wrong.', 50);
  }
});

An explanation of the above code:

1. grunt.verbose.write(msg); logs the message (no newline), but only in --verbose mode.
2. grunt.verbose.ok(); logs OK in green, with a newline.
3. grunt.verbose.or.write(msg).error().error(e.message); does a few things:
4. grunt.verbose.or.write(msg) logs the message (no newline) if not in --verbose mode, and returns the notverbose object.
5. .error() logs ERROR in red, with a newline, and returns the notverbose object.
6. .error(e.message); logs the actual error message (and returns the notverbose object).
7. grunt.fail.warn('Something went wrong.', 50); logs a warning in bright yellow, exiting grunt with exit code 50, unless --force was specified.

Take a look at the built-in tasks source code for more examples.