1 | [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
|
2 |
|
3 | # [The grunt API](api.md) / grunt.file
|
4 |
|
5 | Wildcard expansion, file reading, writing, directory traversing.
|
6 |
|
7 | See the [file lib source](../lib/grunt/file.js) for more information.
|
8 |
|
9 | ## The file API
|
10 | 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.
|
11 |
|
12 | _Note: all file paths are relative to the [grunt.js gruntfile](getting_started.md) unless the current working directory is changed with `grunt.file.setBase` or the `--base` command-line option._
|
13 |
|
14 | ### grunt.file.read
|
15 | Read and return a file's contents. The `encoding` argument defaults to `utf8` if unspecified.
|
16 |
|
17 | ```javascript
|
18 | grunt.file.read(filepath, encoding)
|
19 | ```
|
20 |
|
21 | ### grunt.file.readJSON
|
22 | Read a file's contents, parsing the data as JSON and returning the result.
|
23 |
|
24 | ```javascript
|
25 | grunt.file.readJSON(filepath)
|
26 | ```
|
27 |
|
28 | ### grunt.file.write
|
29 | Write the specified contents to a file, creating intermediate directories if necessary.
|
30 |
|
31 | _If the `--no-write` command-line option is specified, the file won't actually be written._
|
32 |
|
33 | ```javascript
|
34 | grunt.file.write(filepath, contents)
|
35 | ```
|
36 |
|
37 | ### grunt.file.copy
|
38 | Copy a source file to a destination path, creating intermediate directories if necessary.
|
39 |
|
40 | _If the `--no-write` command-line option is specified, the file won't actually be written._
|
41 |
|
42 | ```javascript
|
43 | grunt.file.copy(srcpath, destpath [, options])
|
44 | ```
|
45 |
|
46 | The `options` object has these possible properties:
|
47 |
|
48 | ```javascript
|
49 | var options = {
|
50 | // If specified, the file contents will be parsed as `utf8` and passed into
|
51 | // the function, whose return value will be used as the destination file's
|
52 | // contents.
|
53 | process: processFunction
|
54 | };
|
55 | ```
|
56 |
|
57 | ### grunt.file.mkdir
|
58 | Works like `mkdir -p`. Create a directory along with any intermediate directories.
|
59 |
|
60 | _If the `--no-write` command-line option is specified, directories won't actually be created._
|
61 |
|
62 | ```javascript
|
63 | grunt.file.mkdir(dirpath)
|
64 | ```
|
65 |
|
66 | ### grunt.file.recurse
|
67 | Recurse into a directory, executing `callback` for each file.
|
68 |
|
69 | ```javascript
|
70 | grunt.file.recurse(rootdir, callback)
|
71 | ```
|
72 |
|
73 | The callback function receives the following arguments:
|
74 |
|
75 | ```javascript
|
76 | function callback(abspath, rootdir, subdir, filename) {
|
77 | // The full path to the current file, which is nothing more than
|
78 | // the rootdir + subdir + filename arguments, joined.
|
79 | abspath
|
80 | // The root director, as originally specified.
|
81 | rootdir
|
82 | // The current file's directory, relative to rootdir.
|
83 | subdir
|
84 | // The filename of the current file, without any directory parts.
|
85 | filename
|
86 | }
|
87 | ```
|
88 |
|
89 | ### grunt.file.findup
|
90 | Search for a filename in the given directory followed by all parent directories. Returns the first matching filepath found, otherwise returns `null`.
|
91 |
|
92 | ```javascript
|
93 | grunt.file.findup(rootdir, filename)
|
94 | ```
|
95 |
|
96 | ### grunt.file.isPathAbsolute
|
97 | Is a given file path absolute? Returns a boolean.
|
98 |
|
99 | Like the Node.js [path.join](http://nodejs.org/docs/latest/api/path.html#path_path_join_path1_path2) method, this method will join all arguments together and normalize the resulting path.
|
100 |
|
101 | ```javascript
|
102 | grunt.file.isPathAbsolute(path1 [, path2 [, ...]])
|
103 | ```
|
104 |
|
105 | ### grunt.file.userDir
|
106 | 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.
|
107 |
|
108 | _Like the Node.js [path.join](http://nodejs.org/docs/latest/api/path.html#path_path_join_path1_path2) method, this method will join all arguments together and normalize the resulting path._
|
109 |
|
110 | ```javascript
|
111 | grunt.file.userDir([path1, [, path2 [, ...]]])
|
112 | ```
|
113 |
|
114 | ### grunt.file.setBase
|
115 | Change grunt's current working directory. By default, all file paths are relative to the [grunt.js gruntfile](getting_started.md). This works just like the `--base` command-line option.
|
116 |
|
117 | ```javascript
|
118 | grunt.file.setBase(path1 [, path2 [, ...]])
|
119 | ```
|
120 |
|
121 | Like the Node.js [path.join](http://nodejs.org/docs/latest/api/path.html#path_path_join_path1_path2) method, this method will join all arguments together and normalize the resulting path.
|
122 |
|
123 |
|
124 | ## File Lists and Wildcards
|
125 | Wildcard patterns are resolved using the [glob-whatev library](https://github.com/cowboy/node-glob-whatev). See the [minimatch](https://github.com/isaacs/minimatch) module documentation for more details on supported wildcard patterns.
|
126 |
|
127 | There are also a number of [task-specific file listing methods](api_task.md) that find files inside grunt plugins and task directories.
|
128 |
|
129 | _Note: all file paths are relative to the [grunt.js gruntfile](getting_started.md) unless the current working directory is changed with `grunt.file.setBase` or the `--base` command-line option._
|
130 |
|
131 | ### grunt.file.expand
|
132 | 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.
|
133 |
|
134 | ```javascript
|
135 | grunt.file.expand(patterns)
|
136 | ```
|
137 |
|
138 | ### grunt.file.expandDirs
|
139 | This method behaves the same as `grunt.file.expand` except it only returns directory paths.
|
140 |
|
141 | ```javascript
|
142 | grunt.file.expandDirs(patterns)
|
143 | ```
|
144 |
|
145 | ### grunt.file.expandFiles
|
146 | This method behaves the same as `grunt.file.expand` except it only returns file paths.
|
147 |
|
148 | ```javascript
|
149 | grunt.file.expandFiles(patterns)
|
150 | ```
|
151 |
|
152 | This method is used by many built-in tasks to handle wildcard expansion of the specified source files. See the [concat task source](../tasks/concat.js) for an example.
|
153 |
|
154 | ### grunt.file.expandFileURLs
|
155 | 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).
|
156 |
|
157 | ```javascript
|
158 | grunt.file.expandFileURLs(patternsOrURLs)
|
159 | ```
|
160 |
|
161 | See the [qunit task source](../tasks/qunit.js) for an example.
|