Skip to content
Newer
Older
100644 155 lines (120 sloc) 5.62 KB
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
1 [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
2
495dbaa @cowboy More concat docs tweaks.
authored Feb 4, 2012
3 # concat (built-in task)
8d332e2 @cowboy More concat docs tweaks.
authored Feb 4, 2012
4 Concatenate one or more input files (and/or [directives](helpers_directives.md) output, like `<banner>`) into an output file.
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
5
33d890c @cowboy More concat docs tweaks.
authored Feb 4, 2012
6 ## About
7
8662392 @cowboy More docs.
authored Mar 22, 2012
8 This task is a [multi task](types_of_tasks.md), meaning that grunt will automatically iterate over all `concat` targets if a target is not specified.
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
9
09f2412 @cowboy More docs.
authored Mar 22, 2012
10 _Need some help getting started with grunt? Visit the [getting started](getting_started.md) page. And if you're creating your own tasks or helpers, be sure to check out the [types of tasks](types_of_tasks.md) page as well as the [API documentation](api.md)._
b81594a @cowboy More concat task doc tweaks.
authored Feb 4, 2012
11
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
12 ## A Very Important Note
13 Your `grunt.js` gruntfile **must** contain this code, once and **only** once. If it doesn't, grunt won't work. For the sake of brevity, this "wrapper" code has been omitted from all examples on this page, but it needs to be there.
ecd85d1 @cowboy More docs.
authored Mar 13, 2012
14
15 ```javascript
48cec61 @cowboy Changed back to module.exports in tasks files/gruntfiles vs exports.c…
authored Mar 20, 2012
16 module.exports = function(grunt) {
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
17 // Your grunt code goes in here.
18 };
19 ```
ecd85d1 @cowboy More docs.
authored Mar 13, 2012
20
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
21 ## Project configuration
ecd85d1 @cowboy More docs.
authored Mar 13, 2012
22
8662392 @cowboy More docs.
authored Mar 22, 2012
23 This example shows a brief overview of the [grunt.js gruntfile](getting_started.md) config properties used by the `concat` task. For a more in-depth explanation, see the usage examples.
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
24
25 ```javascript
26 // Project configuration.
27 grunt.initConfig({
28 // Project metadata, used by the <banner> directive.
29 meta: {},
30 // Lists of files to be concatenated.
31 concat: {}
32 });
ecd85d1 @cowboy More docs.
authored Mar 13, 2012
33 ```
34
33d890c @cowboy More concat docs tweaks.
authored Feb 4, 2012
35 ## Usage examples
b81594a @cowboy More concat task doc tweaks.
authored Feb 4, 2012
36
1ab56c0 @cowboy Updating concat docs.
authored Feb 5, 2012
37 ### Concatenating multiple files
38
03814fb @cowboy More docs.
authored Mar 22, 2012
39 In this example, running `grunt concat:dist` (or `grunt concat` because `concat` is a [multi task](types_of_tasks.md)) will simply concatenate the three specified source files, in order, writing the output to `dist/built.js`.
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
40
41 ```javascript
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
42 // Project configuration.
43 grunt.initConfig({
44 concat: {
45 dist: {
46 src: ['src/intro.js', 'src/project.js', 'src/outro.js'],
47 dest: 'dist/built.js'
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored Mar 5, 2012
48 }
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
49 }
50 });
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
51 ```
52
1ab56c0 @cowboy Updating concat docs.
authored Feb 5, 2012
53 ### Banner comments
54
03814fb @cowboy More docs.
authored Mar 23, 2012
55 In this example, running `grunt concat:dist` (or `grunt concat` because `concat` is a [multi task](types_of_tasks.md)) will first strip any preexisting banner comment from the `src/project.js` file, then concatenate the result with a newly-generated banner comment, writing the output to `dist/built.js`.
b81594a @cowboy More concat task doc tweaks.
authored Feb 4, 2012
56
a895117 @cowboy More docs.
authored Mar 13, 2012
57 This generated banner will be the contents of the `meta.banner` underscore template string interpolated with the config object. In this case, those properties are the values imported from the `package.json` file (which are available via the `pkg` config property) plus today's date.
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
58
945f852 @cowboy More docs.
authored Mar 13, 2012
59 _Note: you don't have to use an external JSON file. It's completely valid to create the `pkg` object inline in the config. That being said, if you already have a JSON file, you might as well reference it. See the [directives](helpers_directives.md) page for more information on the `<banner>` and `<json>` directives and their options._
7f6a52b @cowboy More concat docs tweaks.
authored Feb 4, 2012
60
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
61 ```javascript
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
62 // Project configuration.
63 grunt.initConfig({
64 pkg: '<json:package.json>',
65 meta: {
66 banner: '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
67 '<%= grunt.template.today("m/d/yyyy") %> */'
68 },
69 concat: {
70 dist: {
71 src: ['<banner>', '<file_strip_banner:src/project.js>'],
72 dest: 'dist/built.js'
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored Mar 5, 2012
73 }
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
74 }
75 });
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
76 ```
77
1ab56c0 @cowboy Updating concat docs.
authored Feb 5, 2012
78 ### Multiple build targets
79
03814fb @cowboy More docs.
authored Mar 23, 2012
80 In this example, running `grunt concat` will build two separate files. One "basic" version, with the main file essentially just copied to `dist/basic.js`, and another "with_extras" concatenated version written to `dist/with_extras.js`.
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
81
8662392 @cowboy More docs.
authored Mar 22, 2012
82 While each concat target can be built individually by running `grunt concat:basic` or `grunt concat:extras`, running `grunt concat` will build all concat targets. This is because `concat` is a [multi task](types_of_tasks.md).
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
83
84 ```javascript
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
85 // Project configuration.
86 grunt.initConfig({
87 concat: {
88 basic: {
89 src: ['src/main.js'],
90 dest: 'dist/basic.js'
91 },
92 extras: {
93 src: ['src/main.js', 'src/extras.js'],
94 dest: 'dist/with_extras.js'
2ada036 @cowboy Adding some edited docs. Note that many changes in these disc apply t…
authored Mar 5, 2012
95 }
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
96 }
97 });
af4afd2 @cowboy Readme, docs and description "tagline" tweaks.
authored Feb 4, 2012
98 ```
33d890c @cowboy More concat docs tweaks.
authored Feb 4, 2012
99
7943e19 @cowboy More 0.3.0 docs updates.
authored Mar 5, 2012
100 ### Dynamic filenames
101
b389bc5 @cowboy More docs.
authored Mar 13, 2012
102 Filenames can be generated dynamically by using `<%= %>` delimited underscore templates as filenames.
103
03814fb @cowboy More docs.
authored Mar 23, 2012
104 In this example, running `grunt concat:dist` generates a destination file whose name is generated from the `name` and `version` properties of the referenced `package.json` file (via the `pkg` config property).
7943e19 @cowboy More 0.3.0 docs updates.
authored Mar 5, 2012
105
106 ```javascript
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
107 // Project configuration.
108 grunt.initConfig({
109 pkg: '<json:package.json>',
110 concat: {
111 dist: {
112 src: ['src/main.js'],
113 dest: 'dist/<%= pkg.name %>-<%= pkg.version %>.js'
114 }
115 },
116 });
7943e19 @cowboy More 0.3.0 docs updates.
authored Mar 5, 2012
117 ```
118
f185115 @cowboy More docs.
authored Mar 13, 2012
119 ### Advanced dynamic filenames
120
03814fb @cowboy More docs.
authored Mar 23, 2012
121 In this more involved example, running `grunt concat` will build two separate files (because `concat` is a [multi task](types_of_tasks.md)). The destination file paths will be expanded dynamically based on the specified underscore templates, recursively if necessary.
b389bc5 @cowboy More docs.
authored Mar 13, 2012
122
123 For example, if the `package.json` file contained `{"name": "awesome", "version": "1.0.0"}`, the files `dist/awesome/1.0.0/basic.js` and `dist/awesome/1.0.0/with_extras.js` would be generated.
124
125 ```javascript
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
126 // Project configuration.
127 grunt.initConfig({
128 pkg: '<json:package.json>',
129 dirs: {
130 src: 'src/files',
131 dest: 'dist/<%= pkg.name %>/<%= pkg.version %>'
132 },
133 concat: {
134 basic: {
135 src: ['<%= dirs.src %>/main.js'],
136 dest: '<%= dirs.dest %>/basic.js'
b389bc5 @cowboy More docs.
authored Mar 13, 2012
137 },
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
138 extras: {
139 src: ['<%= dirs.src %>/main.js', '<%= dirs.src %>/extras.js'],
140 dest: '<%= dirs.dest %>/with_extras.js'
b389bc5 @cowboy More docs.
authored Mar 13, 2012
141 }
e5fc6c6 @cowboy More docs.
authored Mar 22, 2012
142 }
143 });
b389bc5 @cowboy More docs.
authored Mar 13, 2012
144 ```
145
33d890c @cowboy More concat docs tweaks.
authored Feb 4, 2012
146 ## Helpers
147
b389bc5 @cowboy More docs.
authored Mar 13, 2012
148 A generic `concat` helper is available for use in any other task where file and/or [directive](helpers_directives.md) concatenation might be useful. For example:
33d890c @cowboy More concat docs tweaks.
authored Feb 4, 2012
149
150 ```javascript
41260c3 @cowboy Docs tweaks.
authored Mar 13, 2012
151 var fooPlusBar = grunt.helper('concat', ['foo.txt', 'bar.txt']);
33d890c @cowboy More concat docs tweaks.
authored Feb 4, 2012
152 ```
1416d5b @cowboy Adding links to task source at the bottom of tasks docs.
authored Feb 5, 2012
153
ccd251c @cowboy Docs tweaks.
authored Mar 13, 2012
154 See the [concat task source](../tasks/concat.js) for more information.
Something went wrong with that request. Please try again.