Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 296 lines (198 sloc) 11.291 kB
7ee61b6 @cowboy Docs reorganization.
authored
1 [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
2
3 # The grunt API
4
82a6799 @cowboy More docs.
authored
5 Grunt exposes all of its methods and properties on the `grunt` object that gets passed into the `exports.config` function exported in your [grunt.js gruntfile](configuring.md) or the `exports.tasks` function exported in your [tasks file](tasks_creating.md).
dbaee9c @cowboy More docs.
authored
6
82a6799 @cowboy More docs.
authored
7 For example, your project's [grunt.js gruntfile](configuring.md) might look like this:
dbaee9c @cowboy More docs.
authored
8
9 ```javascript
10 exports.config = function(grunt) {
ee1939e @cowboy More docs.
authored
11
12 // Project configuration.
13 grunt.initConfig({
14 lint: {
15 all: ['grunt.js', 'lib/**/*.js''test/**/*.js']
16 },
17 jshint: {
18 options: {
19 browser: true
20 }
21 }
22 });
23
b2a86d8 @cowboy More docs.
authored
24 // Load tasks from "grunt-sample" grunt plugin installed via Npm.
ee1939e @cowboy More docs.
authored
25 grunt.loadNpmTasks('grunt-sample');
26
27 // Default task.
28 grunt.registerTask('default', 'lint sample');
29
dbaee9c @cowboy More docs.
authored
30 };
31 ```
32
c8e22b4 @cowboy More docs.
authored
33 And if you're creating a [grunt plugin](plugins.md) or just organizing tasks into a folder, a [custom tasks file](tasks_creating.md) might look like this:
dbaee9c @cowboy More docs.
authored
34
35 ```javascript
36 exports.tasks = function(grunt) {
ee1939e @cowboy More docs.
authored
37
38 // Create a new task.
39 grunt.registerTask('awesome', 'Print out "awesome!!!"', function() {
40 var awesome = grunt.helper('awesome');
41 log.write(awesome);
42 });
43
44 // Register a helper.
45 grunt.registerHelper('awesome', function() {
46 return 'awesome!!!';
47 });
48
dbaee9c @cowboy More docs.
authored
49 };
50 ```
51
16c967b @cowboy More docs.
authored
52 But these are just examples. For more information, take a look at the API documentation:
5b73737 @cowboy More docs.
authored
53
48bcd44 @cowboy More docs.
authored
54 ## Config
dbaee9c @cowboy More docs.
authored
55
80581c2 @cowboy More docs.
authored
56
48bcd44 @cowboy More docs.
authored
57 ### grunt.initConfig
82a6799 @cowboy More docs.
authored
58 Initialize a configuration object for the current project. The specified `configObject` is used by tasks and helpers and can also be accessed using the [grunt.config](api_config.md) method. Nearly every project's [grunt.js gruntfile](configuring.md) will call this method.
dbaee9c @cowboy More docs.
authored
59
60 ```javascript
34274e3 @cowboy More docs.
authored
61 grunt.initConfig(configObject)
62 ```
63
31950dd @cowboy More docs.
authored
64 This example contains sample config data for the [lint task](task_lint.md):
34274e3 @cowboy More docs.
authored
65
66 ```javascript
67 grunt.initConfig({
68 lint: {
69 all: ['lib/*.js', 'test/*.js', 'grunt.js']
70 }
71 });
dbaee9c @cowboy More docs.
authored
72 ```
73
5a41466 @cowboy More docs.
authored
74 See the [configuring grunt](configuring.md) page for more configuration examples.
29b12b9 @cowboy More docs.
authored
75
fbc0986 @cowboy More docs.
authored
76 _This method is an alias for the [config.init](api_config.md) method._
dbaee9c @cowboy More docs.
authored
77
48bcd44 @cowboy More docs.
authored
78
0e2160e @cowboy More docs.
authored
79 ## Creating Tasks
48bcd44 @cowboy More docs.
authored
80
80581c2 @cowboy More docs.
authored
81
48bcd44 @cowboy More docs.
authored
82 ### grunt.registerTask
e2bebb6 @cowboy More docs.
authored
83 Register an "alias task" or a task function. This method supports the following two signatures:
dbaee9c @cowboy More docs.
authored
84
cc08918 @cowboy More docs.
authored
85 **Alias task**
5c46902 @cowboy More docs.
authored
86
80581c2 @cowboy More docs.
authored
87 If a string `taskList` is specified, the new task will be an alias for one or more other tasks. Whenever this "alias task" is run, every specified task in `taskList` will be run, in the order specified.
dbaee9c @cowboy More docs.
authored
88
89 ```javascript
34274e3 @cowboy More docs.
authored
90 grunt.registerTask(taskName, taskList)
f531113 @cowboy More docs.
authored
91 ```
92
e2bebb6 @cowboy More docs.
authored
93 This example alias task defines a "default" task whereby the "lint", "qunit", "concat" and "min" tasks are run automatically if grunt is executed without any tasks specified:
94
95 ```javascript
96 task.registerTask('default', 'lint qunit concat min');
97 ```
98
cc08918 @cowboy More docs.
authored
99 **Function task**
5c46902 @cowboy More docs.
authored
100
80581c2 @cowboy More docs.
authored
101 If a `description` and `taskFunction` are passed, the specified function will be executed whenever the task is run. In addition, the specified description will be shown when `grunt --help` is run. Task-specific properties and methods are available inside the task function as properties of the `this` object.
102
103 Note that the `grunt.registerMultiTask` method, explained below, can be used to define a special type of task known as a "multi task."
f531113 @cowboy More docs.
authored
104
105 ```javascript
34274e3 @cowboy More docs.
authored
106 grunt.registerTask(taskName, description, taskFunction)
dbaee9c @cowboy More docs.
authored
107 ```
108
451428f @cowboy More docs.
authored
109 This example task logs `foo, testing 123` if grunt is run via `grunt foo:testing:123`. If the task is run without arguments as `grunt foo` the task logs `foo, no args`.
5dacc94 @cowboy More docs.
authored
110
111 ```javascript
112 grunt.registerTask('foo', 'A sample task that logs stuff.', function(arg1, arg2) {
113 if (arguments.length === 0) {
114 grunt.log.writeln(this.name + ", no args");
115 } else {
116 grunt.log.writeln(this.name + ", " + arg1 + " " + arg2);
117 }
118 });
119 ```
120
82a6799 @cowboy More docs.
authored
121 See the [creating tasks](tasks_creating.md) documentation for more examples of tasks and alias tasks.
f531113 @cowboy More docs.
authored
122
fbc0986 @cowboy More docs.
authored
123 _This method is an alias for the [task.registerTask](api_task.md) method._
f531113 @cowboy More docs.
authored
124
125
48bcd44 @cowboy More docs.
authored
126 ### grunt.registerMultiTask
451428f @cowboy More docs.
authored
127 Register a "multi task." A multi task is a task that implicitly iterates over all of its named sub-properties (AKA targets) if no target was specified. In addition to the default properties and methods, extra multi task-specific properties are available inside the task function as properties of the `this` object.
dbaee9c @cowboy More docs.
authored
128
31950dd @cowboy More docs.
authored
129 Many of the built-in tasks, including the [lint task](task_lint.md), [concat task](task_concat.md) and [min task](task_min.md) are multi tasks.
dbaee9c @cowboy More docs.
authored
130
131 ```javascript
34274e3 @cowboy More docs.
authored
132 grunt.registerMultiTask(taskName, description, taskFunction)
dbaee9c @cowboy More docs.
authored
133 ```
134
82a6799 @cowboy More docs.
authored
135 Given the specified configuration, this example multi task would log `foo: 1,2,3` if grunt was run via `grunt log:foo`, or it would log `bar: hello world` if grunt was run via `grunt log:bar`. If grunt was run as `grunt log` however, it would log `foo: 1,2,3` then `bar: hello world` then `grunt baz: false`.
451428f @cowboy More docs.
authored
136
137 ```javascript
138 grunt.initConfig({
139 log: {
140 foo: [1, 2, 3],
141 bar: 'hello world',
142 baz: false
143 }
144 });
145
146 grunt.registerMultiTask('log', 'Log stuff.', function(target) {
147 grunt.log.writeln(target + ': ' + this.data);
148 });
149 ```
150
82a6799 @cowboy More docs.
authored
151 See the [creating tasks](tasks_creating.md) documentation for more examples of multi tasks.
80581c2 @cowboy More docs.
authored
152
153 _This method is an alias for the [task.registerMultiTask](api_task.md) method._
154
155
48bcd44 @cowboy More docs.
authored
156 ### grunt.registerInitTask
fd45238 @cowboy More docs.
authored
157 Register an "init task." An init task is a task that doesn't require any configuration data, and as such will still run even if grunt can't find a [grunt.js gruntfile](configuring.md). The [init task](task_init.md) is an example of an init task.
dbaee9c @cowboy More docs.
authored
158
159 ```javascript
34274e3 @cowboy More docs.
authored
160 grunt.registerInitTask(taskName, description, taskFunction)
dbaee9c @cowboy More docs.
authored
161 ```
162
fd45238 @cowboy More docs.
authored
163 For an init task example, see the [init task source](../tasks/init.js).
82a6799 @cowboy More docs.
authored
164
5be5bf3 @cowboy More docs.
authored
165 _This method is an alias for the [task.registerInitTask](api_task.md) method._
166
167
18e3d03 @cowboy More docs.
authored
168 ## Inside Tasks
5be5bf3 @cowboy More docs.
authored
169
148d6ee @cowboy More docs.
authored
170 ### this.async
62a16c0 @cowboy More docs.
authored
171 If a task is asynchronous, this method must be invoked to instruct grunt to wait. It returns a handle to a "done" function that should be called when the task has completed. `false` can be passed to the done function to indicate that the task has failed. If this method isn't invoked, the task executes synchronously.
148d6ee @cowboy More docs.
authored
172
173 ```javascript
174 // Tell grunt this task is asynchronous.
175 var done = this.async();
176 // Your async code.
177 setTimeout(function() {
d5405a4 @cowboy More docs.
authored
178 // Let's simulate an error, sometimes.
36cf507 @cowboy More docs.
authored
179 var success = Math.random() > 0.5;
62a16c0 @cowboy More docs.
authored
180 // All done!
36cf507 @cowboy More docs.
authored
181 done(success);
148d6ee @cowboy More docs.
authored
182 }, 1000);
183 ```
5be5bf3 @cowboy More docs.
authored
184
6a891d1 @cowboy More docs.
authored
185 ### this.name
3ee8516 @cowboy More docs.
authored
186 The name of the task, as defined in `grunt.registerTask`. For example, if a "sample" task was run as `grunt sample` or `grunt sample:foo`, inside the task function, `this.name` would be `"sample"`.
6a891d1 @cowboy More docs.
authored
187
188 ### this.nameArgs
3ee8516 @cowboy More docs.
authored
189 The name of the task, as specified with any colon-separated arguments or flags on the command-line. For example, if a "sample" task was run as `grunt sample:foo`, inside the task function, `this.nameArgs` would be `"sample:foo"`.
6a891d1 @cowboy More docs.
authored
190
148d6ee @cowboy More docs.
authored
191 ### this.args
3ee8516 @cowboy More docs.
authored
192 An array of arguments passed to the task. For example, if a "sample" task was run as `grunt sample:foo:bar`, inside the task function, `this.args` would be `["foo", "bar"]`. Note that in multi tasks, the target is removed from the `this.args` array and is not passed into the task function.
148d6ee @cowboy More docs.
authored
193
194 ### this.flags
3ee8516 @cowboy More docs.
authored
195 An object generated from the arguments passed to the task. For example, if a "sample" task was run as `grunt sample:foo:bar`, inside the task function, `this.flags` would be `{foo: true, bar: true}`. In a multi task, the target name is not set as a flag.
196
197 ### this.extraspaths
18e3d03 @cowboy More docs.
authored
198 TODO: re-evaluate
3ee8516 @cowboy More docs.
authored
199
200
201 ## Inside Multi Tasks
202
203 ### this.target
204 In a multi task, this is the name of the target currently being iterated over. For example, if a "sample" multi task was run as `grunt sample:foo` with the config data `{sample: {foo: "bar"}}`, inside the task function, `this.target` would be `"foo"`.
148d6ee @cowboy More docs.
authored
205
206 ### this.data
3ee8516 @cowboy More docs.
authored
207 In a multi task, this is the actual data stored in the grunt config object for the given target. For example, if a "sample" multi task was run as `grunt sample:foo` with the config data `{sample: {foo: "bar"}}`, inside the task function, `this.data` would be `"bar"`.
148d6ee @cowboy More docs.
authored
208
209 ### this.file
48a8956 @cowboy More docs.
authored
210 In a multi task, target data can be stored in two different formats. A relatively basic "compact" format and a much more flexible "full" format. When the compact format is used, that key and value are made available as `this.file.dest` and `this.file.src`, respectively. When the full format is used, the specified `src` and `dest` values are used for `this.file.dest` and `this.file.src`.
148d6ee @cowboy More docs.
authored
211
5870cd6 @cowboy More docs.
authored
212 Note that while grunt supports expanding [templates](api_template.md) for both `src` and `dest`, they only work for the `dest` file path when the _full_ format is used.
6a891d1 @cowboy More docs.
authored
213
18e3d03 @cowboy More docs.
authored
214 ```javascript
215 grunt.initConfig({
216 concat: {
217 // This is the "compact" format.
218 'dist/built.js': ['src/file1.js', 'src/file2.js'],
219 // This is the "full" format.
220 built: {
221 src: ['src/file1.js', 'src/file2.js'],
222 dest: 'dist/built.js'
223 }
224 }
225 });
226 ```
5be5bf3 @cowboy More docs.
authored
227
228
0e2160e @cowboy More docs.
authored
229 ## Loading Externally-Defined Tasks
dbaee9c @cowboy More docs.
authored
230
5be5bf3 @cowboy More docs.
authored
231
48bcd44 @cowboy More docs.
authored
232 ### grunt.loadTasks
e03cb7a @cowboy More docs.
authored
233 Load task-related files from the specified directory, relative to the [grunt.js gruntfile](configuring.md). This method can be used to load task-related files from a locally-installed grunt plugin by specifying the path to that plugin's "tasks" subdirectory.
dbaee9c @cowboy More docs.
authored
234
235 ```javascript
cb7a64a @cowboy More docs.
authored
236 grunt.loadTasks(tasksPath)
dbaee9c @cowboy More docs.
authored
237 ```
238
cb7a64a @cowboy More docs.
authored
239 _This method is an alias for the [task.loadTasks](api_task.md) method._
dbaee9c @cowboy More docs.
authored
240
cb7a64a @cowboy More docs.
authored
241
242 ### grunt.loadNpmTasks
e03cb7a @cowboy More docs.
authored
243 Load tasks and helpers from the specified Npm-installed grunt plugin. If the verion of grunt being run was installed globally via Npm, this will load a global Npm module. If the verion of grunt being run was installed locally via Npm, this will load a local Npm module.
dbaee9c @cowboy More docs.
authored
244
245 ```javascript
cb7a64a @cowboy More docs.
authored
246 grunt.loadNpmTasks(pluginName)
dbaee9c @cowboy More docs.
authored
247 ```
248
cb7a64a @cowboy More docs.
authored
249 _This method is an alias for the [task.loadNpmTasks](api_task.md) method._
250
251
0e2160e @cowboy More docs.
authored
252 ## Defining and Executing Helpers
dbaee9c @cowboy More docs.
authored
253
cb7a64a @cowboy More docs.
authored
254
48bcd44 @cowboy More docs.
authored
255 ### grunt.registerHelper
fbc0986 @cowboy More docs.
authored
256 This method is an alias for the [task.registerHelper](api_task.md) method.
dbaee9c @cowboy More docs.
authored
257
258 Usage:
259
260 ```javascript
34274e3 @cowboy More docs.
authored
261 grunt.registerHelper(helperName, helperFunction)
dbaee9c @cowboy More docs.
authored
262 ```
263
48bcd44 @cowboy More docs.
authored
264 ### grunt.helper
fbc0986 @cowboy More docs.
authored
265 This method is an alias for the [task.helper](api_task.md) method.
dbaee9c @cowboy More docs.
authored
266
267 Usage:
268
269 ```javascript
34274e3 @cowboy More docs.
authored
270 grunt.helper(helperName [, arguments...])
dbaee9c @cowboy More docs.
authored
271 ```
7ee61b6 @cowboy Docs reorganization.
authored
272
b260167 @cowboy More docs.
authored
273
274
275
276
7ee61b6 @cowboy Docs reorganization.
authored
277 ## Internals
278
dbaee9c @cowboy More docs.
authored
279 * [grunt.utils](api_utils.md) - miscellaneous utilities
280 * [grunt.template](api_template.md) - template methods
281 * [grunt.task](api_task.md) - the entire task interface
282 * [grunt.file](api_file.md) - glob expansion, file reading, writing, directory traversing
283 * [grunt.fail](api_fail.md) - more serious than error logging, `fail.warn` and `fail.fatal` will halt everything
284 * [grunt.config](api_config.md) - reading values from the grunt configuration
285 * [grunt.option](api_option.md) - reading values from the command-line options
286 * [grunt.log](api_log.md) - don't use `console.log`, use `log.writeln` instead!
287 * [grunt.verbose](api_verbose.md) - just like `log`, but only logs if `--verbose` was specified.
7ee61b6 @cowboy Docs reorganization.
authored
288
392aef1 @cowboy Removing globals "underscore" and "async" which are now available as …
authored
289 ## External libraries, exposed
290
dbaee9c @cowboy More docs.
authored
291 * [utils.async](api_utils.md) - [Async utilities](https://github.com/caolan/async)
292 * [utils._](api_utils.md) - [Underscore.js](http://underscorejs.org/), including [Underscore.string](https://github.com/epeli/underscore.string)
293 * [utils.hooker](api_utils.md) - [JavaScript hooker](https://github.com/cowboy/javascript-hooker)
392aef1 @cowboy Removing globals "underscore" and "async" which are now available as …
authored
294
7ee61b6 @cowboy Docs reorganization.
authored
295 Unfortunately, I haven't documented everything yet. Fortunately, the source is open and browsable. Have fun!
Something went wrong with that request. Please try again.