Project Scaffolding

grunt-init

Grunt-init 是一个用于自动化项目创建的脚手架工具。它将根据当前环境和对一些问题的回答构建整个目录结构。创建的确切文件和内容取决于所选择的模板以及对所询问问题的回答。

注意：这个独立的实用工具以前是 Grunt 内置的 "init" 任务。有关此更改的更多信息，请参见 Grunt 从 0.3 升级到 0.4 指南。

安装

要使用 grunt-init，您需要全局安装它。

npm install -g grunt-init

这将把 grunt-init 命令放入您的系统路径，使其可以从任何位置运行。

注意：您可能需要使用 sudo 或以管理员身份运行命令行来执行此操作。

使用

使用 grunt-init --help 获取程序帮助和可用模板列表
使用 grunt-init TEMPLATE 基于可用模板创建项目
使用 grunt-init /path/to/TEMPLATE 基于任意位置的模板创建项目

请注意，大多数模板在当前目录中生成其文件，因此如果您不想覆盖现有文件，请务必先切换到新目录。

安装模板

一旦模板安装到您的 ~/.grunt-init/ 目录（Windows 上为 %USERPROFILE%\.grunt-init\），它们就可以通过 grunt-init 使用。建议使用 git 将模板克隆到该目录。例如，grunt-init-jquery 模板可以这样安装：

git clone https://github.com/gruntjs/grunt-init-jquery.git ~/.grunt-init/jquery

注意：如果您希望本地模板名称为 "foobarbaz"，可以在克隆时指定 ~/.grunt-init/foobarbaz。Grunt-init 将使用 ~/.grunt-init/ 目录中实际存在的模板目录名称。

一些 grunt-init 模板是官方维护的：

grunt-init-commonjs - 创建一个 commonjs 模块，包括 Nodeunit 单元测试。（示例"生成"仓库 | 创建过程记录）
grunt-init-gruntfile - 创建一个基本的 Gruntfile。（示例"生成"仓库 | 创建过程记录）
grunt-init-gruntplugin - 创建一个 Grunt 插件，包括 Nodeunit 单元测试。（示例"生成"仓库 | 创建过程记录）
grunt-init-jquery - 创建一个 jQuery 插件，包括 QUnit 单元测试。（示例"生成"仓库 | 创建过程记录）
grunt-init-node - 创建一个 Node.js 模块，包括 Nodeunit 单元测试。（示例"生成"仓库 | 创建过程记录）

自定义模板

您可以创建和使用自定义模板。您的模板必须遵循上述模板的相同结构。

名为 my-template 的示例模板将遵循以下常规文件结构：

my-template/template.js - 主模板文件。
my-template/rename.json - 模板特定的重命名规则，作为模板处理。
my-template/root/ - 要复制到目标位置的文件。

假设这些文件存在于 /path/to/my-template，则使用命令 grunt-init /path/to/my-template 来处理模板。多个唯一命名的模板可以存在于同一目录中。

此外，如果将此自定义模板放置在 ~/.grunt-init/ 目录（Windows 上为 %USERPROFILE%\.grunt-init\），它将自动可用，可以直接使用 grunt-init my-template 调用。

复制文件

只要模板使用 init.filesToCopy 和 init.copyAndProcess 方法，root/ 子目录中的任何文件都将在运行 init 模板时复制到当前目录。

请注意，除非设置了 noProcess 选项，否则所有复制的文件都将作为模板处理，任何 {% %} 模板都将针对收集的 props 数据对象进行处理。请参见 jquery 模板作为示例。

重命名或排除模板文件

rename.json 描述了 sourcepath 到 destpath 的重命名映射。sourcepath 必须是相对于 root/ 文件夹的待复制文件的路径，但 destpath 值可以包含 {% %} 模板，描述目标路径将是什么。

如果将 false 指定为 destpath，则不会复制该文件。另外，支持对 srcpath 使用 glob 模式。

指定默认提示答案

每个初始化提示要么有一个硬编码的默认值，要么查看当前环境以尝试确定该默认值。如果您想覆盖特定提示的默认值，可以在可选的 macOS 或 Linux ~/.grunt-init/defaults.json 或 Windows %USERPROFILE%\.grunt-init\defaults.json 文件中进行。

例如，我的 defaults.json 文件如下所示，因为我想使用与默认名称稍微不同的名称，我想排除我的电子邮件地址，并希望自动指定作者 URL：

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

注意：在所有内置提示都被记录之前，您可以在源代码中找到它们的名称和默认值。

定义初始化模板

exports.description

这个简短的模板描述将在用户运行 grunt init 或 grunt-init 以显示所有可用的初始化模板列表时与模板名称一起显示。

exports.description = descriptionString;

exports.notes

如果指定，这个可选的扩展描述将在显示任何提示之前显示。这是一个很好的地方，向用户提供一些帮助，解释命名约定，哪些提示可能是必需的或可选的等。

exports.notes = notesString;

exports.warnOn

如果这个可选的（但推荐的）通配符模式或通配符模式数组匹配，Grunt 将中止并显示警告，用户可以使用 --force 覆盖。这在初始化模板可能覆盖现有文件的情况下非常有用。

exports.warnOn = wildcardPattern;

虽然最常见的值将是 '*'，匹配任何文件或目录，但使用的 minimatch 通配符模式语法允许很大的灵活性。例如：

exports.warnOn = 'Gruntfile.js';    // 警告 Gruntfile.js 文件。
exports.warnOn = '*.js';            // 警告任何 .js 文件。
exports.warnOn = '*';               // 警告任何非点文件或非点目录。
exports.warnOn = '.*';              // 警告任何点文件或点目录。
exports.warnOn = '{.*,*}';          // 警告任何文件或目录（点或非点）。
exports.warnOn = '!*/**';           // 警告任何文件（忽略目录）。
exports.warnOn = '*.{png,gif,jpg}'; // 警告任何图像文件。

// 这是最后一个示例的另一种写法。
exports.warnOn = ['*.png', '*.gif', '*.jpg'];

exports.template

虽然 exports 属性在此函数外定义，但所有实际的初始化代码都在此函数内指定。三个参数被传递到这个函数中。grunt 参数是对 grunt 的引用，包含所有 grunt 方法和库。init 参数是一个包含特定于此初始化模板的方法和属性的对象。done 参数是一个在初始化模板执行完毕时必须调用的函数。

exports.template = function(grunt, init, done) {
  // 参见"在初始化模板内部"部分。
};

在初始化模板内部

init.addLicenseFiles

将正确命名的许可证文件添加到文件对象。

var files = {};
var licenses = ['MIT'];
init.addLicenseFiles(files, licenses);
// files === {'LICENSE-MIT': 'licenses/LICENSE-MIT'}

init.availableLicenses

返回可用许可证的数组。

var licenses = init.availableLicenses();
// licenses === [ 'Apache-2.0', 'GPL-2.0', 'MIT', 'MPL-2.0' ]

init.copy

给定一个绝对或相对的源路径，以及一个可选的相对目标路径，复制一个文件，可选地通过传递的回调处理。

init.copy(srcpath[, destpath], options)

init.copyAndProcess

遍历传递对象中的所有文件，将源文件复制到目标，处理内容。

init.copyAndProcess(files, props[, options])

init.defaults

用户在 defaults.json 中指定的默认初始化值。

init.defaults

init.destpath

绝对目标文件路径。

init.destpath()

init.expand

与 grunt.file.expand 相同。

返回与给定通配符模式匹配的所有文件或目录路径的唯一数组。此方法接受逗号分隔的通配符模式或通配符模式数组。以 ! 开头的模式将从返回的数组中排除。模式按顺序处理，因此包含和排除的顺序很重要。

init.expand([options, ] patterns)

init.filesToCopy

返回一个包含要复制的文件的对象，其中包含绝对源路径和相对目标路径，根据 rename.json 中的规则重命名（或省略）。

var files = init.filesToCopy(props);
/* files === { '.gitignore': 'template/root/.gitignore',
  '.jshintrc': 'template/root/.jshintrc',
  'Gruntfile.js': 'template/root/Gruntfile.js',
  'README.md': 'template/root/README.md',
  'test/test_test.js': 'template/root/test/name_test.js' } */

init.getFile

获取单个任务文件路径。

init.getFile(filepath[, ...])

init.getTemplates

返回所有可用模板的对象。

init.getTemplates()

init.initSearchDirs

初始化搜索初始化模板的目录。template 是模板的位置。还将包括 ~/.grunt-init/ 和 grunt-init 中的核心初始化任务。

init.initSearchDirs([filename])

init.process

启动进程开始提示输入。

init.process(options, prompts, done)

init.process({}, [
  // 提示这些值
  init.prompt('name'),
  init.prompt('description'),
  init.prompt('version')
], function(err, props) {
  // 全部完成，对属性执行某些操作
});

init.prompt

提示用户输入值。

init.prompt(name[, default])

init.prompts

所有提示的对象。

var prompts = init.prompts;

Built-in prompts

author_email

Author's email address to use in the package.json. Will attempt to find a default value from the user's git config.

author_name

Author's full name to use in the package.json and copyright notices. Will attempt to find a default value from the user's git config.

author_url

A public URL to the author's website to use in the package.json.

bin

A relative path from the project root for a cli script.

bugs

A public URL to the project's issues tracker. Will default to the GitHub issue tracker if the project has a GitHub repository.

description

A description of the project. Used in the package.json and README files.

grunt_version

A valid semantic version range descriptor of Grunt the project requires.

homepage

A public URL to the project's home page. Will default to the GitHub URL if a GitHub repository.

jquery_version

If a jQuery project, the version of jQuery the project requires. Must be a valid semantic version range descriptor.

licenses

The license(s) for the project. Multiple licenses are separated by spaces. The licenses built-in are: MIT, MPL-2.0, GPL-2.0, and Apache-2.0. Defaults to MIT. Add custom licenses with init.addLicenseFiles.

main

The primary entry point of the project. Defaults to the project name within the lib folder.

name

The name of the project. Will be used heavily throughout the project template. Defaults to the current working directory.

node_version

The version of Node.js the project requires. Must be a valid semantic version range descriptor.

npm_test

The command to run tests on your project. Defaults to grunt.

repository

Project's git repository. Defaults to a guess of a GitHub URL.

title

A human readable project name. Defaults to the actual project name altered to be more human readable.

version

The version of the project. Defaults to the first valid semantic version, 0.1.0.

Found an error in the documentation? File an issue.