<commit_before>[Grunt homepage](http://gruntjs.com/) | [Documentation table of contents](toc.md)

# Getting Started With Grunt

Grunt is a task-based command line build tool written in JavaScript. *[Why does grunt exist?](/)*

## Installing the CLI
In order to use grunt, you'll want to install the command line interface (CLI) globally.

```bash
npm install -g grunt-cli
```

This will put the `grunt` command in your system path, allowing it to be run from anywhere.

**Note:** You may need to use `sudo` or run your command shell as Administrator to do this.

## How the CLI works

Each time `grunt` is run, it looks for a [Gruntfile] in the current folder. If none is found, it will traverse up the directory tree trying to find one. Because of this, you can run `grunt` from any subfolder in your project.

If a [Gruntfile] is found, the CLI loads a local installation of the grunt library, applies the configuration from your [Gruntfile], and executes any tasks you've requested for it to run.

## Preparing a grunt project
A typical setup will involve adding two files to your project: [package.json] and [Gruntfile.js][gruntfile].

**[package.json]**: This file is used by [npm] to store metadata for projects published as npm modules.  You will list grunt and the grunt plugins your project needs as [devDependencies] in this file.

**[Gruntfile]**: This file is named `Gruntfile.js` or `Gruntfile.coffee` and is used by grunt to configure or define tasks and load grunt plugins.

## package.json

The `package.json` file belongs in the root directory of your project, next to your [Gruntfile], and should be committed with your project source.  Running `npm install` in the same folder as a `package.json` file will install the correct version of each dependency listed within.

Here are a few ways to create a `package.json` file for your project:

* A `package.json` file is automatically generated by most [init task] templates.
* The [npm init] command will create a basic `package.json` file for you.
* Start with the example below, and expand as needed to this [specification][json].

```js
{
  "name": "project",
  "version": "0.1.0",
  "devDependencies": {
    "grunt-contrib-jshint": "~0.4.0",
    "grunt-contrib-nodeunit": "~0.4.0",
    "grunt": "~0.4.0"
  }
}
```

### Adding dependencies
The easiest way to add grunt and grunt plugins to an existing `package.json` is with the command `npm install --save-dev <module>`.  Not only will this install `<module>` locally, but it will automatically be added to the [devDependencies] section, using a [tilde version range].

For example, this will install the latest version of grunt in your project folder, adding it to your devDependencies:

```bash
npm install --save-dev grunt
```

The same can be done for grunt plugins. Be sure to commit the updated `package.json` file with your project when you're done!

## The gruntfile
The `Gruntfile.js` or `Gruntfile.coffee` file is a valid JavaScript or CoffeeScript file, placed in the root directory of your project—next to the `package.json` file—and should be committed with your project source.

A Gruntfile is comprised of the following parts:

* The "wrapper" function
* Project and task configuration
* Loading grunt plugins and tasks
* Defining custom tasks inline

### An example gruntfile
In the following gruntfile, project metadata is imported into the grunt config from a `package.json` file, and the [uglify task] is configured to minify a source file and generate a banner comment dynamically using that metadata.

```js
module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
      },
      dist: {
        src: 'src/<%= pkg.name %>.js',
        dest: 'dist/<%= pkg.name %>.min.js'
      }
    }
  });

  // Load the plugin that provides the "uglify" task.
  grunt.loadNpmTasks('grunt-contrib-uglify');

  // Default task(s).
  grunt.registerTask('default', ['uglify']);

};
```

### The "wrapper" function
Every Gruntfile (and grunt plugin) uses this basic format, and all of your grunt code will be specified inside this function:

```js
module.exports = function(grunt) {
  // Do grunt-related things in here
};
```

### Project and task configuration
Most grunt tasks rely on configuration data defined in an object passed to the [grunt.initConfig] method.

In this example, `grunt.file.readJSON('package.json')` imports the JSON metadata stored in `package.json` into the grunt config. Because `<% %>` template strings may reference any config properties, configuration data like filepaths and file lists may be specified this way to reduce repetition.

You may store any arbitrary data inside of the configuration object, and as long as it doesn't conflict with properties your tasks require, it will be otherwise ignored. Also, because this is JavaScript, you're not limited to JSON; you may use any valid JS here. You can even programmatically generate the configuration if necessary.

Like most tasks, the [uglify task] expects its configuration to be specified in a property of the same name. Here, the `banner` option is specified, along with a single uglify target named `dist` that minifies a single source file to a single destination file.

((( link out to the options object page and file lists page )))

```js
// Project configuration.
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  uglify: {
    options: {
      banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
    },
    dist: {
      src: 'src/<%= pkg.name %>.js',
      dest: 'dist/<%= pkg.name %>.min.js'
    }
  }
});
```

### Loading grunt plugins and tasks
Many commonly used tasks like [concatenation], [minification][uglify task] and [linting] are available as [grunt plugins]. As long as a plugin is specified in `package.json` as a dependency, and has been installed via `npm install`, it may be enabled inside your [Gruntfile] with a simple command:

```js
// Load the plugin that provides the "uglify" task.
grunt.loadNpmTasks('grunt-contrib-uglify');
```

Tasks in external `.js` files can be loaded from a directory with the [grunt.loadTasks] method.

**Note:** You can list all available tasks with the command `grunt --help`.

### Defining custom tasks inline
If your project only uses tasks provided by [grunt plugins], you might not need to define any custom tasks. That being said, if you want grunt to perform one or more tasks by default when running `grunt` with no arguments, you'll need to create a default task.

To do this, create an [alias task][custom tasks].  In the example below, when running `grunt` (or `grunt default`) at the command line, the uglify task will be run. This is functionally the same as running `grunt uglify`.

```js
// Default task(s).
grunt.registerTask('default', ['uglify']);
```

If you want to run multiple tasks in succession with a single command, just add more to the array.

```js
// Build my project
grunt.registerTask('default', ['jshint','concat','uglify']);
```

If you don't need pre-made tasks, and you don't want to [load your custom tasks from an external folder][grunt.loadTasks], you can register tasks right inside your [Gruntfile].

Here is an extremely simple example:

```js
module.exports = function(grunt) {

  // A very basic default task.
  grunt.registerTask('default', 'Log some stuff.', function() {
    grunt.log.write('Logging some stuff...').ok();
  });

};
```

For more information about writing tasks, check out the developer documentation.

[gruntfile]: #the-gruntfile
[package.json]: #packagejson
[npm]: https://npmjs.org/
[devDependencies]: https://npmjs.org/doc/json.html#devDependencies
[json]: https://npmjs.org/doc/json.html
[npm init]: https://npmjs.org/doc/init.html
[init task]: task_init.md
[tilde version range]: https://npmjs.org/doc/json.html#Tilde-Version-Ranges
[uglify task]: http://github.com/gruntjs/grunt-contrib-uglify
[grunt.initConfig]: api.md
[concatenation]: https://github.com/gruntjs/grunt-contrib-concat
[linting]: https://github.com/gruntjs/grunt-contrib-jshint
[grunt plugins]: TODO
[custom tasks]: TODO
[grunt.loadTasks]: https://github.com/gruntjs/grunt/blob/devel/docs/api.md#loading-externally-defined-tasks<commit_msg>Getting Started Guide tweaks.<commit_after>[Grunt homepage](http://gruntjs.com/) | [Documentation table of contents](toc.md)

# Getting Started With Grunt

Grunt is a task-based command line build tool written in JavaScript. *[Why does grunt exist?](/)*

## Installing the CLI
In order to use grunt, you'll want to install the command line interface (CLI) globally.

```bash
npm install -g grunt-cli
```

This will put the `grunt` command in your system path, allowing it to be run from anywhere.

**Note:** You may need to use `sudo` or run your command shell as Administrator to do this.

## How the CLI works

Each time `grunt` is run, it looks for a [Gruntfile] in the current folder. If none is found, it will traverse up the directory tree trying to find one. Because of this, you can run `grunt` from any subfolder in your project.

If a [Gruntfile] is found, the CLI loads a local installation of the grunt library, applies the configuration from your [Gruntfile], and executes any tasks you've requested for it to run.

## Preparing a grunt project
A typical setup will involve adding two files to your project: [package.json] and [the Gruntfile][Gruntfile].

**[package.json]**: This file is used by [npm] to store metadata for projects published as npm modules.  You will list grunt and the grunt plugins your project needs as [devDependencies] in this file.

**[The Gruntfile][Gruntfile]**: This file is named `Gruntfile.js` or `Gruntfile.coffee` and is used by grunt to configure or define tasks and load grunt plugins.

## package.json

The `package.json` file belongs in the root directory of your project, next to [the Gruntfile][Gruntfile], and should be committed with your project source.  Running `npm install` in the same folder as a `package.json` file will install the correct version of each dependency listed within.

Here are a few ways to create a `package.json` file for your project:

* A `package.json` file is automatically generated by most [init task] templates.
* The [npm init] command will create a basic `package.json` file for you.
* Start with the example below, and expand as needed, following this [specification][json].

```js
{
  "name": "my-project-name",
  "version": "0.1.0",
  "devDependencies": {
    "grunt": "~0.4.0",
    "grunt-contrib-jshint": "~0.1.0",
    "grunt-contrib-nodeunit": "~0.1.0"
  }
}
```

### Adding dependencies
The easiest way to add grunt and grunt plugins to an existing `package.json` is with the command `npm install <module> --save-dev`.  Not only will this install `<module>` locally, but it will automatically be added to the [devDependencies] section, using a [tilde version range].

For example, this will install the latest version of grunt in your project folder, adding it to your devDependencies:

```bash
npm install grunt --save-dev
```

The same can be done for grunt plugins. Be sure to commit the updated `package.json` file with your project when you're done!

## The Gruntfile
The `Gruntfile.js` or `Gruntfile.coffee` file is a valid JavaScript or CoffeeScript file, placed in the root directory of your project—next to the `package.json` file—and should be committed with your project source.

A Gruntfile is comprised of the following parts:

* The "wrapper" function
* Project and task configuration
* Loading grunt plugins and tasks
* Custom inline tasks

### An example Gruntfile
In the following Gruntfile, project metadata is imported into the grunt config from a `package.json` file, and the [grunt-contrib-uglify plugin] `uglify` task is configured to minify a source file and generate a banner comment dynamically using that metadata.

```js
module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    uglify: {
      options: {
        banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
      },
      dist: {
        src: 'src/<%= pkg.name %>.js',
        dest: 'dist/<%= pkg.name %>.min.js'
      }
    }
  });

  // Load the plugin that provides the "uglify" task.
  grunt.loadNpmTasks('grunt-contrib-uglify');

  // Default task(s).
  grunt.registerTask('default', ['uglify']);

};
```

### The "wrapper" function
Every Gruntfile (and grunt plugin) uses this basic format, and all of your grunt code must be specified inside this function:

```js
module.exports = function(grunt) {
  // Do grunt-related things in here
};
```

### Project and task configuration
Most grunt tasks rely on configuration data defined in an object passed to the [grunt.initConfig] method.

In this example, `grunt.file.readJSON('package.json')` imports the JSON metadata stored in `package.json` into the grunt config. Because `<% %>` template strings may reference any config properties, configuration data like filepaths and file lists may be specified this way to reduce repetition.

You may store any arbitrary data inside of the configuration object, and as long as it doesn't conflict with properties your tasks require, it will be otherwise ignored. Also, because this is JavaScript, you're not limited to JSON; you may use any valid JS here. You can even programmatically generate the configuration if necessary.

Like most tasks, the [grunt-contrib-uglify plugin] `uglify` task expects its configuration to be specified in a property of the same name. Here, the `banner` option is specified, along with a single uglify target named `dist` that minifies a single source file to a single destination file.

((( link out to the options object page and file lists page )))

```js
// Project configuration.
grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  uglify: {
    options: {
      banner: '/*! <%= pkg.name %> <%= grunt.template.today("yyyy-mm-dd") %> */\n'
    },
    dist: {
      src: 'src/<%= pkg.name %>.js',
      dest: 'dist/<%= pkg.name %>.min.js'
    }
  }
});
```

### Loading grunt plugins and tasks
Many commonly used tasks like [concatenation], [minification][grunt-contrib-uglify plugin] and [linting] are available as [grunt plugins]. As long as a plugin is specified in `package.json` as a dependency, and has been installed via `npm install`, it may be enabled inside your [Gruntfile] with a simple command:

```js
// Load the plugin that provides the "uglify" task.
grunt.loadNpmTasks('grunt-contrib-uglify');
```

Tasks defined in external `.js` files can be loaded from with the [grunt.loadTasks] method.

**Note:** You can list all available tasks with the command `grunt --help`.

### Custom inline tasks
If your project only uses tasks provided by [grunt plugins], you might not need to define any custom tasks. That being said, if you want grunt to perform one or more tasks by default when running `grunt` with no arguments, you'll need to create a default task.

To do this, create an [alias task][custom tasks].  In the example below, when running `grunt` (or `grunt default`) at the command line, the uglify task will be run. This is functionally the same as running `grunt uglify`.

```js
// Default task(s).
grunt.registerTask('default', ['uglify']);
```

If you want to run multiple tasks in succession with a single command, just add more tasks to the array, with any arguments they might need.

```js
// Build my project
grunt.registerTask('default', ['jshint', 'concat', 'uglify']);
```

If you don't need pre-made tasks, and you don't want to [load your custom tasks from an external folder][grunt.loadTasks], you can register tasks right inside your [Gruntfile].

Here is an extremely simple example [Gruntfile] that doesn't even utilize task configuration:

```js
module.exports = function(grunt) {

  // A very basic default task.
  grunt.registerTask('default', 'Log some stuff.', function() {
    grunt.log.write('Logging some stuff...').ok();
  });

};
```

For more information about writing custom tasks or grunt plugins, check out the [developer documentation].

[Gruntfile]: #the-gruntfile
[package.json]: #packagejson
[npm]: https://npmjs.org/
[devDependencies]: https://npmjs.org/doc/json.html#devDependencies
[json]: https://npmjs.org/doc/json.html
[npm init]: https://npmjs.org/doc/init.html
[init task]: task_init.md
[tilde version range]: https://npmjs.org/doc/json.html#Tilde-Version-Ranges
[grunt.initConfig]: api.md
[grunt-contrib-uglify plugin]: http://github.com/gruntjs/grunt-contrib-uglify
[concatenation]: https://github.com/gruntjs/grunt-contrib-concat
[linting]: https://github.com/gruntjs/grunt-contrib-jshint
[grunt.loadTasks]: https://github.com/gruntjs/grunt/blob/devel/docs/api.md#loading-externally-defined-tasks
[grunt plugins]: TODO
[custom tasks]: TODO
[developer documentation]: TODO
{'fraction_non_alphanumeric': 0.10879643213426442, 'fraction_numerical': 0.001408368053517986, 'mean_word_length': 4.205253512522908, 'pattern_counts': {'":': 12, '<': 25, '<?xml version=': 0, '>': 25, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4476249', 'n_tokens_mistral': 5072, 'n_tokens_neox': 4825, 'n_words': 2190}