Adds a simple banner to files

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-banner --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-banner');

Or if you are using matchdep it will be included along with other grunt-* tasks by using this line of JavaScript:

require('matchdep').filterDev('grunt-*').forEach(grunt.loadNpmTasks);

grunt-banner renamed its task from banner to usebanner as a banner is often used to hold a banner template for a number of grunt plugins.

In your project's Gruntfile, add a section named usebanner to the data object passed into grunt.initConfig().

The wildcard selector * is perfectly valid for selecting targets to add a banner to.

grunt.initConfig({
  usebanner: {
    taskName: {
      options: {
        position: 'top',
        banner: '// banner text <%= templates encouraged %>',
        linebreak: true
      },
      files: {
        src: [ 'path/to/file.ext', 'path/to/another/*.ext' ]
      }
    }
  }
})

Type: String
Default: 'top'
Value range: 'top' or 'bottom'

The position to place the banner - either the top or bottom (other values will default to top).

Type: String

The text to use as a banner. Templated strings are perfectly acceptable and encouraged.

Type: String

Allows the banner to be added only if the supplied pattern matches.

Type: Boolean
Default: true

Set linebreak to true to add a line break between banner and file content.

Type: Function

Allows the banner to be generated for each file using the output of the process function.

In this example an appConfig is read from a JSON file and used to populate a banner template which is then used by grunt-banner to place at the top of some files. Each file in the array will have the banner placed on to it and all .js files in the /more-scripts/ folder will have a banner thanks to the * wildcard.

var appConfig = grunt.file.readJSON( 'app-config.json' ) || {};
grunt.initConfig({
  banner: '/* <%= appConfig.info.name %> - version <%= appConfig.info.version %> - ' +
          '<%= grunt.template.today("dd-mm-yyyy") %>\n' +
          '<%= appConfig.info.description %>\n ' +
          '&#169 <%= grunt.template.today("yyyy") %> <%= appConfig.info.author.name %> ' +
          '- <%= appConfig.info.author.email %> */\n',
  usebanner: {
    dist: {
      options: {
        position: 'top',
        banner: '<%= banner %>'
      },
      files: {
        src: [ 'scripts/main-min.js', 'stylesheets/main-min.css', 'more-scripts/*.js' ]
      }
    }
  }
})

By supplying a process function you effectively take control of how the banner is generated, the task is still responsible for placing it. In essence, it replaces the need for a banner object being specified in your grunt config as you are creating it from code for each file. This gives you the flexibility to add file-specific data to your banners.

This example uses grunt templating to generate a banner that references the file name it is being appended to. Run the test cases to see this in action.

usebanner: {
  dist: {
    options: {
      position: 'top',
      process: function ( filepath ) {
        return grunt.template.process(
          '// banner for file: <%= filename %>',
          {
            data: {
              filename: filepath.match(/\/([^/]*)$/)[1]
            }
          }
        );
      }
    },
    files: {
      src: [ 'test/tmp/someProcess.js' ]
    }
  }
}

grunt-banner simply adds the banner to the head or foot of the files that are specified by the array passed to files.src, it makes no attempt to see if a banner already exists and it is up to the user to ensure that the file should not already contain a banner. To this end it is recommended to use the grunt-contrib-clean task and only add banners to production-ready code.

In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Task submitted by Matt Styles @personalurban