| 1 | # grunt
|
| 2 | Grunt is a task-based command line build tool for JavaScript projects.
|
| 3 |
|
| 4 | _Grunt is currently in beta. While I'm already using it on multiple projects, it might have a minor issue or two. And things might change before its final release, based on your feedback. Please try it out in a project, and [make suggestions][issues] or [report bugs][issues]!_
|
| 5 |
|
| 6 | ## Getting started
|
| 7 | Be sure to read the [getting started guide](/cowboy/grunt/blob/master/docs/getting_started.md), which is a complete guide to configuring grunt for your project. In addition, check out the [example gruntfiles](/cowboy/grunt/blob/master/docs/example_gruntfiles.md) which highlight a number of fairly common configurations.
|
| 8 |
|
| 9 | ## Built-in tasks
|
| 10 | As of now, grunt has the following predefined tasks that you can use in your project:
|
| 11 |
|
| 12 | * [concat](/cowboy/grunt/blob/master/docs/task_concat.md) - Concatenate files.
|
| 13 | * [init](/cowboy/grunt/blob/master/docs/task_init.md) - Generate project scaffolding from a predefined template.
|
| 14 | * [lint](/cowboy/grunt/blob/master/docs/task_lint.md) - Validate files with [JSHint][jshint].
|
| 15 | * [min](/cowboy/grunt/blob/master/docs/task_min.md) - Minify files with [UglifyJS][uglify].
|
| 16 | * [qunit](/cowboy/grunt/blob/master/docs/task_qunit.md) - Run [QUnit][qunit] unit tests in a headless [PhantomJS][phantom] instance.
|
| 17 | * [server](/cowboy/grunt/blob/master/docs/task_server.md) - Start a static web server.
|
| 18 | * test - Run unit tests with [nodeunit][nodeunit].
|
| 19 | * watch - Run predefined tasks whenever watched files change.
|
| 20 |
|
| 21 | _(More documentation forthcoming)_
|
| 22 |
|
| 23 | ## Custom tasks
|
| 24 | In addition to the built-in tasks, you can create your own tasks. Don't like a built-in task's default behavior? Override it. Check out the [grunt API documentation](/cowboy/grunt/blob/master/docs/api.md) and the [built-in tasks source](/cowboy/grunt/blob/master/tasks) for everything you need to know about creating custom tasks.
|
| 25 |
|
| 26 | ## Documentation
|
| 27 | Take a look at the [documentation table of contents][docs] for all the things.
|
| 28 |
|
| 29 | ## Why does grunt exist?
|
| 30 | Doing all this stuff manually is a total pain, and building all this stuff into a gigantic Makefile / Jakefile / Cakefile / Rakefile / ?akefile that's maintained across all my projects was also becoming a total pain. Since I always found myself performing the same tasks over and over again, for every project, it made sense to build a task-based build tool.
|
| 31 |
|
| 32 | Being primarily a JavaScript developer, I decided to use [Node.js][node] and [npm][npm] because the dependencies I most care about ([JSHint][jshint] and [UglifyJS][uglify]) were already npm modules. That being said, while Node.js was designed to support highly-concurrent asynchronous-IO-driven web servers, it was clearly NOT designed to make command-line build tools. But none of that matters, because grunt works. Just install it and see.
|
| 33 |
|
| 34 | ## Installing grunt
|
| 35 |
|
| 36 | Grunt is available as an [npm][npm] module. If you install grunt globally via `npm install -g grunt`, it will be available for use in all of your projects. Once grunt has been installed, you can type `grunt --help` at the command line for more information. And if you want to see grunt "grunt" itself, cd into grunt's directory and type `grunt`
|
| 37 |
|
| 38 | _Note: in Windows, you may need to run grunt as `grunt.cmd`. See the [FAQ](/cowboy/grunt/blob/master/docs/faq.md) for more Windows-specific information._
|
| 39 |
|
| 40 | For projects already using grunt, you're done. Otherwise, if you're adding grunt to an existing project or starting from scratch, check out the [getting started guide](/cowboy/grunt/blob/master/docs/getting_started.md), which is a complete guide to configuring grunt for your project.
|
| 41 |
|
| 42 | ## Release History
|
| 43 | _(Until v1.0.0, this will only be updated when major or breaking changes are made)_
|
| 44 |
|
| 45 | * 2012/03/23 - v0.3.0 - Too many changes to list. But in brief: completely reorganized the API, removed all globals, added docs and examples for nearly everything, built a preliminary plugin system (that still needs to be tested). PLEASE RTFM OK? THX U.
|
| 46 | * 2012/02/03 - v0.2.14 - Added a server task (which starts a static webserver for your tasks). The qunit task now uses PhantomJS instead of Zombie.js (4768 of 4971 jQuery unit test pass, neat), and supports both file wildcards as well as http:// or https:// urls. (static webserver, anyone?). Grunt should no longer "hang" when done.
|
| 47 | * 2012/01/29 - v0.2.5 - Added a "qunit" task as well as an init "jquery" template (as of now, there are also "node" and "commonjs" init templates).
|
| 48 | * 2012/01/22 - v0.2.1 - Removed handlebars, templates are universally handled by underscore now. Changed init task template tags from <% %> to {% %}. Banners beginning with /*! will no longer be stripped.
|
| 49 | * 2012/01/22 - v0.2.0 - Added "init" task with a sample template, reworked a lot of code. Hopefully it's backwards-compatible.
|
| 50 | * 2012/01/11 - v0.1.0 - Initial release.
|
| 51 |
|
| 52 | ## License
|
| 53 | Copyright (c) 2012 "Cowboy" Ben Alman
|
| 54 | Licensed under the MIT license.
|
| 55 | <http://benalman.com/about/license/>
|
| 56 |
|
| 57 |
|
| 58 | [docs]: /cowboy/grunt/blob/master/docs/toc.md
|
| 59 | [docs-init]: /cowboy/grunt/blob/master/docs/task_init.md
|
| 60 | [issues]: /cowboy/grunt/issues
|
| 61 |
|
| 62 | [node]: http://nodejs.org/
|
| 63 | [npm]: http://npmjs.org/
|
| 64 | [jshint]: http://www.jshint.com/
|
| 65 | [uglify]: https://github.com/mishoo/UglifyJS/
|
| 66 | [nodeunit]: https://github.com/caolan/nodeunit
|
| 67 | [qunit]: http://docs.jquery.com/QUnit
|
| 68 | [phantom]: http://www.phantomjs.org/
|