Upgrading from 0.3 to 0.4

0.4 及更早的版本不再维护。有关更多信息和其他支持选项，请查看此处。

注意，即使您熟悉 grunt，也建议阅读新的入门指南。

Grunt 现在分为三个部分：grunt、grunt-cli 和 grunt-init。

1. npm 模块 grunt 应该本地安装到您的项目中。它包含运行任务、加载插件等的代码和逻辑。
2. npm 模块 grunt-cli 应该全局安装。它将 grunt 命令放入您的 PATH，以便您可以在任何地方执行它。它本身不做任何事；其工作是加载和运行已本地安装到您项目中的 Grunt，无论版本如何。有关为什么发生这种变化的更多信息，请阅读 npm 1.0：全局与本地安装。
3. init 任务已被拆分为其自己的 npm 模块 grunt-init。应使用 npm install -g grunt-init 全局安装，并使用 grunt-init 命令运行。在接下来的几个月里，Yeoman 将完全取代 grunt-init。有关更多信息，请参见 grunt-init 项目页面。

Grunt 0.3 注意事项

如果您从 Grunt 0.3 升级，请确保卸载全局 grunt：

npm uninstall -g grunt

注意，对于 0.3.x 版本，插件名称和任务配置选项可能与"Gruntfile"部分中显示的不同。

对于 0.3.x 版本的 Grunt，此文件名为 grunt.js。

预先存在的任务和插件

所有 grunt-contrib-* 系列插件都已准备好用于 Grunt 0.4。然而，为 Grunt 0.3 编写的第三方插件不太可能在不更新的情况下继续使用 0.4。我们正在积极与插件作者合作，以确保这种情况尽快得到解决。

即将发布的 Grunt 版本将专注于解耦 grunt 的架构，以便插件不受未来更新的影响。

要求

• Grunt 现在要求 Node.js 版本 >= 0.8.0

Gruntfile

• "Gruntfile" 已从 grunt.js 更改为 Gruntfile.js。
• 在您的 Gruntfile.coffee 项目 Gruntfile 或 *.coffee 任务文件中支持 CoffeeScript（自动转换为 JS）。

有关更多信息，请参见入门指南的"Gruntfile"部分。

核心任务现在是 Grunt 插件

Grunt 0.3 中包含的八个核心任务现在是单独的 Grunt 插件。每个都是一个离散的 npm 模块，必须按照入门指南的"加载 Grunt 插件和任务"部分作为插件安装。

• concat → grunt-contrib-concat 插件
• init → 独立的 grunt-init 实用工具
• lint → grunt-contrib-jshint 插件
• min → grunt-contrib-uglify 插件
• qunit → grunt-contrib-qunit 插件
• server → grunt-contrib-connect 插件
• test → grunt-contrib-nodeunit 插件
• watch → grunt-contrib-watch 插件

一些任务名称和选项已更改。请务必查看上面链接的每个插件的文档，了解最新的配置详细信息。

Configuration

The configuration format for Grunt 0.4 tasks has been standardized and greatly enhanced. See the Configuring tasks guide, as well as individual plugin documentation for more information.

• File globbing (wildcard) patterns may now be negated to exclude matched files.
• Tasks now support a standard options object.
• Tasks now support a standard files object.

<% %> style template strings specified as config data inside the Gruntfile are automatically expanded, see the grunt.template documentation for more information.

Directives have been removed, but their functionality has been retained. These replacements can be made:

• '<config:prop.subprop>' → '<%= prop.subprop %>'
• '<json:file.json>' → grunt.file.readJSON('file.json')
• '<file_template:file.js>' → grunt.template.process(grunt.file.read('file.js'))

Instead of specifying a banner in a file list with '<banner>' or '<banner:prop.subprop>', the grunt-contrib-concat and grunt-contrib-uglify plugins each have a banner option.

Instead of stripping banners from files individually with '<file_strip_banner:file.js>', the grunt-contrib-concat and grunt-contrib-uglify plugins each have an option to strip/preserve banners.

Alias task changes

When specifying an alias task, the list of tasks to run must now be specified as an array.

// v0.3.x (old format)
grunt.registerTask("default", "jshint nodeunit concat");
// v0.4.x (new format)
grunt.registerTask("default", ["jshint", "nodeunit", "concat"]);

Task arguments may now contain spaces

The aforementioned alias task change (task lists must be specified as an array) makes this possible. Just be sure to surround task arguments containing spaces with quotes when specifying them on the command line, so they can be properly parsed.

grunt my-task:argument-without-spaces "other-task:argument with spaces"

Character encodings

The file.defaultEncoding method was added to normalize character encodings, and all grunt.file methods have been updated to support the specified encoding.

Helpers

Grunt's helper system has been removed in favor of node require. For a concise example on how to share functionality between Grunt plugins, please see grunt-lib-legacyhelpers. Plugin authors are encouraged to upgrade their plugins.

API

The Grunt API saw substantial changes from 0.3 to 0.4.

• grunt
  • Removed grunt.registerHelper and grunt.renameHelper methods.
• grunt.config
  • Changed config.get method to automatically recursively expand <% %> templates.
  • Added config.getRaw method that will retrieve raw (unexpanded) config data.
  • Changed config.process method to now process a value as if it had been retrieved from the config, expanding templates recursively. This method is called internally inside of config.get, but not inside of config.getRaw.
• grunt.event added so that tasks may emit events.
• grunt.fail
  • Won't emit a beep if --no-color option specified.
  • Added fail.code exit code map.
  • Removed fail.warnAlternate method.
• grunt.file
  • Tasks are no longer automatically loaded from ~/.grunt/tasks/ directory (install them locally to your project!).
  • Added file.defaultEncoding method for normalizing character encoding across all grunt.file methods.
  • Added file.delete method.
  • Added relatively self-explanatory file.exists, file.isDir, file.isFile, file.isLink, file.isPathCwd, file.isPathInCwd, file.doesPathContain, file.arePathsEquivalent testing methods.
  • Added file.match and file.isMatch methods to facilitate matching wildcard patterns against file paths.
  • Added file.expandMapping method for use in generating 1-to-1 src-dest file mappings.
  • Added file.readYAML method.
  • Changed file.findup to use the findup-sync module.
  • Changed file.glob to use the glob module.
  • Added file.minimatch which exposes the minimatch module.
  • Removed file.userDir method (moved into grunt-init).
  • Removed file.clearRequireCache method.
  • Removed file.expandFiles and file.expandDirs methods, use the filter option of file.expand instead.
  • Removed file.expandFileURLs method. Don't specify URLs where files should be specified (eg. the qunit task now allows for a urls option).
• grunt.task
  • Tasks registered with both task.registerTask and task.registerMultiTask get a this.options method.
  • Added task.normalizeMultiTaskFiles method to facilitate the normalization of multi task files objects into the this.file property.
  • Removed task.registerHelper and task.renameHelper methods.
  • Removed task.searchDirs property.
  • Removed task.expand task.expandDirs task.expandFiles task.getFile task.readDefaults methods (moved into grunt-init).
• grunt.package reflects the metadata stored in grunt's package.json.
• grunt.version is the current version of Grunt as a string.
• grunt.template
  • Added template.addDelimiters method to add new template delimiters.
  • Added template.setDelimiters method to select template delimiters.
  • The init and user template delimiters have been removed, but you can add them in again if you need to with template.addDelimiters (grunt-init uses this to enable the {% %} template delimiters).
• grunt.util replaces the now-removed grunt.utils.
  • Changed util._ to use Lo-Dash
  • Added the util.callbackify method.
  • Changed the util.spawn method to be much better behaved and pass more consistent arguments into its callback.

Task / plugin authors

Plugin authors, please indicate clearly on your repository README which version number of your Grunt plugin breaks compatibility with Grunt 0.3.

Tasks

• Multi tasks
  • Multiple src-dest file mappings may now be specified per target in a files object (this is optional).
• this.files / grunt.task.current.files
  • The this.files property is an array of src-dest file mapping objects to be iterated over in your multi task. It will always be an array, and you should always iterate over it, even if the most common use case is to specify a single file.
  • Each src-dest file mapping object has a src and dest property (and possibly others, depending on what the user specified). The src property is already expanded from whatever glob pattern the user may have specified.
• this.filesSrc / grunt.task.current.filesSrc
  • The this.filesSrc property is a reduced, uniqued array of all files matched by all specified src properties. Useful for read-only tasks.
• this.options / grunt.task.current.options
  • The this.options method may be used within tasks to normalize options. Inside a task, you may specify options defaults like: var options = this.options({option: 'defaultvalue', ...});

Plugins

• An updated gruntplugin template has been created for Grunt 0.4-compatible plugins, and is available in the standalone grunt-init.

Troubleshooting

• If you had previously installed a development version of Grunt 0.4 or any grunt-contrib plugins, be sure to flush your npm cache with npm cache clean first to ensure that you are pulling the final version of Grunt and grunt-contrib plugins.