SemanSemantic-UItic-UI/node/node_modules/grunt/docs/task_init.md

Grunt homepage | Documentation table of contents

init (built-in task)

Generate project scaffolding from a predefined template.

About

The init task initializes a new project, based on the current environment and the answers to a few questions. Once complete, a grunt.js configuration file will be generated along with a complete directory structure, including a basic readme, license, package.json, sample source files and unit tests (etc).

The exact files and contents created depend on the template chosen along with the answers to the questions asked.

Unlike other tasks, init should only ever be run once for a project. Typically, it is run at the very beginning before work has begun, but it can be run later. Just keep in mind that new files are generated, so for existing projects, ensure that everything is already committed first.

Usage examples

Change to a new directory, and type in grunt init:TEMPLATE where TEMPLATE is one of the following templates. Answer the questions. Watch grunt do it's thing. Done. Now you have fully initialized project scaffolding that you can customize, grunt and publish.

Built-in templates

The init task currently supports a number of built-in templates.

gruntfile

Generated via grunt init:gruntfile, this customizable template creates a single grunt.js gruntfile based on the answers to a few questions and some highly advanced "fuzzy logic" that tries to determine source and unit test paths. This is the template you want to use to generate a gruntfile for an existing project.

If your code is DOM-related, QUnit unit tests will be used, otherwise Nodeunit unit tests will be used. Where appropriate, predefined lint, concat and minification tasks are generated. Also, depending on the library used, JSHint globals may be predefined (just jQuery for now).

You will most likely need to edit the generated grunt.js file before running grunt. If you run grunt after generating grunt.js, and it exits with errors, edit the grunt.js file!

See an example repo generated by this template along with the creation transcript.

commonjs

Generated via grunt init:commonjs, this customizable template creates an entire project directory structure with a grunt.js gruntfile, Npm-friendly package.json file, sample CommonJS source file and Nodeunit unit tests.

In addition, predefined lint, concat and minification tasks are generated.

See an example repo generated by this template along with the creation transcript.

jquery

Generated via grunt init:jquery, this customizable template creates an entire project directory structure with a grunt.js gruntfile, jQuery package.json file, jQuery plugin file and QUnit unit tests.

In addition, predefined lint, concat and minification tasks are generated.

See an example repo generated by this template along with the creation transcript.

node

Generated via grunt init:node, this customizable template creates an entire project directory structure with a grunt.js gruntfile, Npm package.json file, sample Node.js source file and Nodeunit unit tests.

See an example repo generated by this template along with the creation transcript.

Specifying default prompt answers

Each init prompt either has a default value hard-coded or it looks at the current enviroment to attempt to determine that default value. If you want to override a particular prompt's default value, you can do so in the optional OS X or Linux ~/.grunt/tasks/init/defaults.json or Windows %USERPROFILE%\.grunt\tasks\init\defaults.json file.

For example, my defaults.json file looks like this, because I want to use a slightly different name than the default name, I want to exclude my email address, and I want to specify an author url automatically.

{
  "author_name": "\"Cowboy\" Ben Alman",
  "author_email": "none",
  "author_url": "http://benalman.com/"
}

Note: until all the built-in prompts have been documented, you can find each prompt name by looking for the prompt_for helpers' argument in the init templates' source .js files.

Overriding template files

You can override any init template file, even the init template itself.

For example, the "jquery" init template exists inside of grunt at this path:

• tasks/init/jquery.js

A set of jquery-template-specific rename rules exists at this path:

• tasks/init/jquery/rename.json

And any files to be copied by this template (because the template uses the init.filesToCopy and init.copyAndProcess methods), exist here:

• tasks/init/jquery/root/

Any of these files can be overridden via a referenced grunt plugin or tasks directory, OR via your grunt.file.userDir which is %USERPROFILE%\.grunt\ on Windows, and ~/.grunt/ on OS X or Linux. This directory structure mimics grunt's internal directory structure.

So you can override any of the aforementioned things for a given init template TEMPLATE with these OS X / linux paths:

• ~/.grunt/tasks/init/TEMPLATE.js
• ~/.grunt/tasks/init/TEMPLATE/rename.json
• ~/.grunt/tasks/init/TEMPLATE/root/

Or these Windows paths (%USERPROFILE% is generally your Documents and Settings directory):

• %USERPROFILE%\.grunt\tasks\init\TEMPLATE.js
• %USERPROFILE%\.grunt\tasks\init\TEMPLATE\rename.json
• %USERPROFILE%\.grunt\tasks\init\TEMPLATE\root\

If you wanted to change the gruntfile init template grunt.js file, you could copy grunt's own tasks/init/gruntfile/root/grunt.js to ~/.grunt/tasks/init/gruntfile/root/grunt.js (or the Windows equivalent), edit it as you see fit, and when you run grunt init:gruntfile grunt will use your file.

Assuming the template uses the init.filesToCopy and init.copyAndProcess methods, you can add any additional files into that "root" folder, with any arbitrarily-nested directory structure, and those files will be copied to the current directory when the init template is run.

For example, since the gruntfile init template is just two files, the tasks/init/gruntfile.js template and the tasks/init/gruntfile/root/grunt.js file-to-be-copied, you could completely change its behavior by overriding both of those files.

Renaming or excluding template files

If, for some reason, you want to rename or exclude files, you can edit the aforementioned rename.json which describes a map of sourcepath to destpath values. The sourcepath must be the path of the file-to-be-copied relative to the root/ folder, but the destpath value can contain {% %} init templates, as in any init file, and describes what the destination path will be. See the jquery init template rename.json file for an example.

A few notes about rename.json:

• If false is specified for the destpath the file will not be copied.
• The rename.json file is merged using grunt.task.readDefaults so it overrides built-in values.

Creating custom templates

You create a custom template the exact same way you override init templates and their files, you just use a unique template name. in your userDir, just create a ~/.grunt/tasks/init/MYTEMPLATE.js and any other relevant files. See the "Overriding template files" and "Renaming or excluding template files" sections for all the details.

Defining an init template

exports.description

This brief template description will be displayed along with the template name when the user runs grunt init or grunt init: to display a list of all available init templates.

exports.description = descriptionString;

exports.notes

If specified, this optional extended description will be displayed before any prompts are displayed. This is a good place to give the user a little help explaining naming conventions, which prompts may be required or optional, etc.

exports.notes = notesString;

exports.warnOn

If this optional (but recommended) wildcard pattern or array of wildcard patterns is matched, grunt will abort with a warning that the user can override with --force. This is very useful in cases where the init template could potentially override existing files.

exports.warnOn = wildcardPattern;

While the most common value will be '*', matching any file or directory, the minimatch wildcard pattern syntax used allows for a lot of flexibility. For example:

exports.warnOn = 'grunt.js';        // Warn on a grunt.js file.
exports.warnOn = '*.js';            // Warn on any .js file.
exports.warnOn = '*';               // Warn on any non-dotfile or non-dotdir.
exports.warnOn = '.*';              // Warn on any dotfile or dotdir.
exports.warnOn = '{.*,*}';          // Warn on any file or dir (dot or non-dot).
exports.warnOn = '!*/**';           // Warn on any file (ignoring dirs).
exports.warnOn = '*.{png,gif,jpg}'; // Warn on any image file.

// This is another way of writing the last example.
exports.warnOn = ['*.png', '*.gif', '*.jpg'];

exports.template

While the exports properties are defined outside this function, all the actual init code is specified inside. Three arguments are passed into this function. The grunt argument is a reference to grunt, containing all the grunt methods and libs. The init argument is an object containing methods and properties specific to this init template. The done argument is a function that must be called when the init template is done executing.

exports.template = function(grunt, init, done) {
  // See the "Inside an init template" section.
};

Inside an init template

(Documentation coming soon)

Built-in prompts

(Documentation coming soon)

See the init task source for more information.