Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

185 lines (128 sloc) 7.428 kb

Grunt homepage | Documentation table of contents

The grunt API / grunt.file

Wildcard expansion, file reading, writing, directory traversing.

See the file lib source for more information.

The file API

There are many provided methods for reading and writing files, as well as traversing the filesystem and finding files by wildcard patterns. Many of these methods are wrappers around core Node.js file functionality, but with additional error handling and logging.

Note: all file paths are relative to the grunt.js gruntfile unless the current working directory is changed with grunt.file.setBase or the --base command-line option.

grunt.file.read

Read and return a file's contents. The encoding argument defaults to utf8 if unspecified.

grunt.file.read(filepath, encoding)

grunt.file.readJSON

Read a file's contents, parsing the data as JSON and returning the result.

grunt.file.readJSON(filepath)

grunt.file.write

Write the specified contents to a file, creating intermediate directories if necessary.

If the --no-write command-line option is specified, the file won't actually be written.

grunt.file.write(filepath, contents)

grunt.file.copy

Copy a source file to a destination path, creating intermediate directories if necessary.

If the --no-write command-line option is specified, the file won't actually be written.

grunt.file.copy(srcpath, destpath [, options])

The options object has these possible properties:

var options = {
  // If specified, the file contents will be parsed as `utf8` and passed into
  // the function, whose return value will be used as the destination file's
  // contents. If this function returns false, the file copy will be aborted.
  process: processFunction,
  // These optional wildcard patterns will be matched against the filepath using
  // grunt.file.isMatch. If a specified wildcard pattern matches, the file will
  // not be processed via `processFunction`. Note that `true` may also be
  // specified to prvent processing.
  noProcess: wildcardPatterns
};

grunt.file.mkdir

Works like mkdir -p. Create a directory along with any intermediate directories.

If the --no-write command-line option is specified, directories won't actually be created.

grunt.file.mkdir(dirpath)

grunt.file.recurse

Recurse into a directory, executing callback for each file.

grunt.file.recurse(rootdir, callback)

The callback function receives the following arguments:

function callback(abspath, rootdir, subdir, filename) {
  // The full path to the current file, which is nothing more than
  // the rootdir + subdir + filename arguments, joined.
  abspath
  // The root director, as originally specified.
  rootdir
  // The current file's directory, relative to rootdir.
  subdir
  // The filename of the current file, without any directory parts.
  filename
}

grunt.file.findup

Search for a filename in the given directory followed by all parent directories. Returns the first matching filepath found, otherwise returns null.

grunt.file.findup(rootdir, filename)

grunt.file.isPathAbsolute

Is a given file path absolute? Returns a boolean.

Like the Node.js path.join method, this method will join all arguments together and normalize the resulting path.

grunt.file.isPathAbsolute(path1 [, path2 [, ...]])

grunt.file.userDir

Return a file path relative to the user's .grunt directory, which is %USERPROFILE%\.grunt\ on Windows, and ~/.grunt/ on OS X or Linux. If no file path is specified, the base user .grunt directory path will be returned. If the specified path is not found, null is returned.

Windows users: %USERPROFILE% is generally your Documents and Settings directory.

Like the Node.js path.join method, this method will join all arguments together and normalize the resulting path.

grunt.file.userDir([path1, [, path2 [, ...]]])

grunt.file.setBase

Change grunt's current working directory. By default, all file paths are relative to the grunt.js gruntfile. This works just like the --base command-line option.

grunt.file.setBase(path1 [, path2 [, ...]])

Like the Node.js path.join method, this method will join all arguments together and normalize the resulting path.

File Lists and Wildcards

Wildcard patterns are resolved using the glob-whatev library. See the minimatch module documentation for more details on supported wildcard patterns.

There are also a number of task-specific file listing methods that find files inside grunt plugins and task directories.

Note: all file paths are relative to the grunt.js gruntfile unless the current working directory is changed with grunt.file.setBase or the --base command-line option.

grunt.file.expand

Return a unique array of all file or directory paths that match the given wildcard pattern(s). This method accepts one or more comma separated wildcard patterns as well as an array of wildcard patterns.

The options object supports all minimatch options.

grunt.file.expand([options, ] patterns)

grunt.file.expandDirs

This method behaves the same as grunt.file.expand except it only returns directory paths.

grunt.file.expandDirs([options, ] patterns)

grunt.file.expandFiles

This method behaves the same as grunt.file.expand except it only returns file paths.

grunt.file.expandFiles([options, ] patterns)

This method is used by many built-in tasks to handle wildcard expansion of the specified source files. See the concat task source for an example.

grunt.file.expandFileURLs

Return a unique array of all file:// URLs for files that match the given wildcard pattern(s). Any absolute file://, http:// or https:// URLs specified will be passed through. This method accepts one or more comma separated wildcard patterns (or URLs), as well as an array of wildcard patterns (or URLs).

grunt.file.expandFileURLs(patternsOrURLs)

See the qunit task source for an example.

grunt.file.isMatch

Match one or more wildcard patterns against a file path. If any of the specified matches, return true otherwise return false. This method accepts a single string wildcard pattern as well as an array of wildcard patterns. Note that true may also be specified to prvent processing.

grunt.file.isMatch(patterns, filepath)

Patterns without slashes will be matched against the basename of the path if it contains slashes, eg. pattern *.js will match filepath path/to/file.js.

External libraries

grunt.file.glob

glob-whatev - Synchronous file globbing utility.

Jump to Line
Something went wrong with that request. Please try again.