• Stars
    star
    190
  • Rank 197,295 (Top 4 %)
  • Language
    Scala
  • License
    Apache License 2.0
  • Created over 9 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

sbt-header is an sbt plugin for creating file headers, e.g. copyright headers

sbt-header

License

sbt-header is an sbt plugin for creating or updating file headers, e.g. copyright headers.

Getting started

In order to add the sbt-header plugin to your build, add the following line to project/plugins.sbt:

addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.6.0") // Check the latest version above or look at the release tags

Then in your build.sbt configure the following settings:

organizationName := "Heiko Seeberger"
startYear := Some(2015)
licenses += ("Apache-2.0", new URL("https://www.apache.org/licenses/LICENSE-2.0.txt"))

This configuration will apply Apache License 2.0 headers to Scala and Java files. sbt-header provides two tasks: headerCreate and headerCheck, which are described in the following sub sections. For more information on how to customize sbt-header, please refer to the Configuration section.

Creating headers

In order to create or update file headers, execute the headerCreate task:

> headerCreate
[info] Headers created for 2 files:
[info]   /Users/heiko/projects/sbt-header/sbt-header-test/test.scala
[info]   /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala

The task is incremental, meaning that it will not look at files that have not seen changes since the last time the task was run.

Checking headers

In order to check whether all files have headers (for example for CI), execute the headerCheck task:

> headerCheck
[error] (compile:checkHeaders) There are files without headers!
[error]   /Users/heiko/projects/sbt-header/sbt-header-test/test.scala
[error]   /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala

headerCheck will not modify any files but will cause the build to fail if there are files without a license header.

Requirements

  • Java 8 or higher
  • sbt 1.0.0 or higher

Configuration

By default sbt-header tries to infer the license header you want to use from the organizationName, startYear and licenses settings. For this to work, sbt-header requires the licenses setting to contain exactly one entry. The first component of that entry has to be the SPDX license identifier of one of the supported licenses.

Setting the license to use explicitly

If you can not setup your build in a way that sbt-header can detect the license you want to use (see above), you can set the license to use explicitly:

headerLicense := Some(HeaderLicense.MIT("2015", "Heiko Seeberger"))

This will also be given precedence if a license has been auto detected from project settings.

Build in licenses

The most common licenses have been pre-canned in License. They can either be detected using their SPDX identifier or by setting them explicitly.

License SPDX identifier
Apache License, Version 2.0 Apache-2.0
BSD 2 Clause BSD-2-Clause
BSD 3 Clause BSD-3-Clause
GNU General Public License v3 or later GPL-3.0-or-later
GNU General Public License v3 only GPL-3.0-only
GNU General Public License v3 (deprecated) GPL-3.0
GNU Lesser General Public License v3 or later LGPL-3.0-or-later
GNU Lesser General Public License v3 only LGPL-3.0-only
GNU Lesser General Public License v3 (deprecated) LGPL-3.0
GNU Affero General Public License v3 or later AGPL-3.0-or-later
GNU Affero General Public License v3 only AGPL-3.0-only
GNU Affero General Public License v3 (deprecated) AGPL-3.0
MIT License MIT
Mozilla Public License, v. 2.0 MPL-2.0

Using the short SPDX license identifier syntax

If you want to use the following syntax:

  /*
   * Copyright 2015 Heiko Seeberger
   *
   * SPDX-License-Identifier: BSD-3-Clause
   */

You have two possibilites:

  • If you are using auto-detection, you just need to add the following to your build.sbt
headerLicenseStyle := HeaderLicenseStyle.SpdxSyntax
  • On the other hand, if you are defining your license explicitly, you'll have to pass the style when defining the headerLicense attribute:
headerLicense := Some(HeaderLicense.MIT("2015", "Heiko Seeberger", HeaderLicenseStyle.SpdxSyntax))

Using a custom license text

If you don't want to use one of the built-in licenses, you can define a custom license text using the Custom case class:

headerLicense := Some(HeaderLicense.Custom(
  """|Copyright (c) Awesome Company 2015
     |
     |This is the custom License of Awesome Company
     |""".stripMargin
))

Note that you don't need to add comment markers like // or /*. The comment style is configured on a per file type basis (see next section).

Configuring comment styles

Comment styles are configured on a per file type basis. The default is to apply C Style block comments to Scala and Java files. No other comment styles are predefined. If you want to create comments for example for your XML files, you have to add the corresponding mapping manually (see below). The build-in comment styles are defined in CommentStyle:

Name Description
cStyleBlockComment C style block comments (blocks starting with "/*" and ending with "*/")
cppStyleLineComment C++ style line comments (lines prefixed with "//")
hashLineComment Hash line comments (lines prefixed with "#")
twirlStyleComment Twirl style comment (blocks starting with "@*" and ending with "*@")
twirlStyleBlockComment Twirl style block comments (comment blocks with a frame made of "*")

To override the configuration for Scala/Java files or add a configuration for some other file type, use the headerMapping setting:

headerMappings := headerMappings.value + (HeaderFileType.scala -> HeaderCommentStyle.cppStyleLineComment)

Custom comment creators

You can customize how content gets created by providing your own CommentCreator. For example, this would be a (crude) way to preserve the copyright year in existing headers but still update the rest:

CommentStyle.cStyleBlockComment.copy(commentCreator = new CommentCreator() {
  val Pattern = "(?s).*?(\\d{4}(-\\d{4})?).*".r
  def findYear(header: String): Option[String] = header match {
   case Pattern(years, _) => Some(years)
    case _                 => None
  }
  override def apply(text: String, existingText: Option[String]): String = {
    val newText = CommentStyle.cStyleBlockComment.commentCreator.apply(text, existingText)
    existingText
      .flatMap(findYear)
      .map(year => newText.replace("2017", year))
      .getOrElse(newText)
  }
})

Excluding files

To exclude some files, use the sbt's file filters:

excludeFilter.in(headerSources) := HiddenFileFilter || "*Excluded.scala"
excludeFilter.in(headerResources) := HiddenFileFilter || "*.xml"

Empty line between header and body

If an empty line header should be added between the header and the body of a file (defaults to true):

headerEmptyLine := false

Using an auto plugin

If your build uses an auto plugin for common settings, make sure to add HeaderPlugin to requires:

import de.heikoseeberger.sbtheader.HeaderPlugin

object Build extends AutoPlugin {
  override def requires = ... && HeaderPlugin
  ...
}

Adding headers to files in other configurations

By default sbt-header takes Compile and Test configurations into account. If you need more, just add them:

headerSettings(It, MultiJvm)

Automation

If you want to automate header creation/update on compile, enable the AutomateHeaderPlugin:

lazy val myProject = project
  .in(file("."))
  .enablePlugins(AutomateHeaderPlugin)

By default automation takes Compile and Test configurations into account. If you need more, just add them:

automateHeaderSettings(It, MultiJvm)

Integration with other plugins

This plugin by default only handles managedSources and managedResources in Compile and Test. For this reason you need to tell sbt-header if it should also add headers to additional files managed by other plugins.

sbt-twirl / play projects

To use sbt-header in a project using sbt-twirl (for example a Play web project), the Twirl templates have to be added to the sources handled by sbt-header. Add the following to your build definition:

import de.heikoseeberger.sbtheader.FileType
import play.twirl.sbt.Import.TwirlKeys

headerMappings := headerMappings.value + (FileType("html") -> HeaderCommentStyle.twirlStyleBlockComment)

headerSources.in(Compile) ++= sources.in(Compile, TwirlKeys.compileTemplates).value

sbt-header supports two comment styles for Twirl templates. twirlStyleBlockComment will produce simple twirl block comments, while twirlStyleFramedBlockComment will produce framed twirl comments.

twirlStyleBlockComment comment style:

@*
 * This is a simple twirl block comment
 *@

twirlStyleFramedBlockComment comment style:

@**********************************
 * This is a framed twirl comment *
 **********************************@

sbt-boilerplate

In order to use sbt-header with sbt-boilerplate plugin add the following to your build definition:

def addBoilerplate(confs: Configuration*) = confs.foldLeft(List.empty[Setting[_]]) { (acc, conf) =>
  acc ++ Seq(
    headerSources in conf ++= (((sourceDirectory in conf).value / "boilerplate") ** "*.template").get),
    headerMappings        += (FileType("template") -> HeaderCommentStyle.cStyleBlockComment)
  )
}

addBoilerplate(Compile, Test)

This adds src/{conf}/boilerplate/**.scala in the list of files handled by sbt-headers for conf, where conf is either Compile or Test.

Migrating from 1.x

This section contains migration notes from version 1.x of sbt-header to version 2.x. The latest release of the 1.x line is 1.8.0. You can find the documentation of that release in the corresponding git tag.

Changed task names and settings keys

The names of all tasks and settings have been changed from 1.x to 2.x. Furthermore types of settings have changed. The following tables give an overview of the changes:

Changed task names:

Old Name New Name
createHeaders headerCreate
checkHeaders headerCheck

Changed settings:

Old Name : Old Type New Name: New Type
headers : Map[String, (Regex, String)] headerMappings : Map[FileType, CommentStyle]
- headerLicense : Option[License]
exclude : Seq[String] removed in favor of sbt include/excude filters

createFrom method

sbt-header 1.x featured some default header mappings as well as the createFrom method, which could be used to easily define header mappings:

headers := createFrom(Apache2_0, "2015", "Heiko Seeberger")

This method has been removed and the default mappings for Scala and Java files has been added as default mapping to the headerMappings setting.

Custom licenses

In sbt-header 1.x when you needed to use a custom license this would typically look like this:

headers := Map(
  "scala" -> (
    HeaderPattern.cStyleBlockComment,
    """|/*
       | * Copyright 2015 Awesome Company
       | */
       |""".stripMargin
  )
)

In sbt-header 2.x, licenses are defined as instances of de.hseeberger.sbtheader.License. Further more, the license is only defined once and not per file type. So the above in 2.x is equivalent to:

headerLicense := Some(HeaderLicense.Custom(
    """|Copyright 2015 Awesome Company
       |""".stripMargin
))

Note that you only need to define the license text, but not the comment markers. The latter are configured via the headerMappings setting. The configuration above will use the default mappings which apply C style block comments to Java and Scala files. If you have mappings for additional file types, please add these to the headerMappings setting.

Dropped features

In sbt-header 1.x it was possible to define different licenses for different files types, e.g.:

headers := Map(
  "scala" -> Apache2_0("2015", "Heiko Seeberger"),
  "java" -> MIT("2015", "Heiko Seeberger")
)

Since we believe most of the projects out there will only ever have one license, we dropped this feature without replacement. In sbt-header 2.x users have to define a single license for the whole project using the headerLicense setting (or let sbt-header infer it from the licenses project setting, see above) and a mapping from file type to comment style using the headerMappings setting.

Contribution policy

Contributions via GitHub pull requests are gladly accepted from their original author. Along with any pull requests, please state that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.

License

This code is open source software licensed under the Apache 2.0 License.

More Repositories

1

sbt

sbt, the interactive build tool
Scala
4,685
star
2

sbt-native-packager

sbt Native Packager
Scala
1,582
star
3

sbt-dependency-graph

sbt plugin to create a dependency graph for your project
Scala
1,240
star
4

sbt-jmh

"Trust no one, bench everything." - sbt plugin for JMH (Java Microbenchmark Harness)
Scala
783
star
5

sbt-eclipse

Plugin for sbt to create Eclipse project definitions
Scala
719
star
6

sbt-release

A release plugin for sbt
Scala
640
star
7

sbt-buildinfo

I know this because build.sbt knows this.
Scala
545
star
8

sbt-web

Library for building sbt plugins for the web
Scala
366
star
9

sbt-git

A git plugin for sbt
Scala
343
star
10

zinc

Scala incremental compiler library, used by sbt and other build tools
Scala
324
star
11

docker-sbt

Official sbt docker images
Dockerfile
313
star
12

sbt-dynver

An sbt plugin to dynamically set your version from git
Scala
295
star
13

sbt-ci-release

sbt plugin to automate Sonatype releases from GitHub Actions
Scala
274
star
14

sbt-onejar

Packages your project using One-JARβ„’
Scala
268
star
15

sbt-scalariform

sbt plugin adding support for source code formatting using Scalariform
Scala
258
star
16

sbt-fresh

sbt-plugin to create an opinionated fresh sbt project
Scala
235
star
17

sbt-github-actions

An sbt plugin which makes it easier to build with GitHub Actions
Scala
192
star
18

sbt-bintray

fresh packages delivered from your sbt console
Scala
180
star
19

sbt-site

Site generation for sbt
Scala
175
star
20

sbt-protobuf

sbt plugin for compiling protobuf files
Scala
174
star
21

sbt-start-script

SBT Plugin to create a "start" script to run the program
Scala
144
star
22

sbt-pgp

PGP plugin for sbt
Scala
141
star
23

sbt-groll

sbt plugin to roll the Git history
Scala
134
star
24

junit-interface

Implementation of sbt's test interface for JUnit
Java
132
star
25

sbt-unidoc

sbt plugin to create a unified Scaladoc or Javadoc API document across multiple subprojects.
Scala
127
star
26

sbt-jacoco

an sbt plugin for JaCoCo Code Coverage
Scala
123
star
27

sbt-jni

SBT Plugin to ease working with JNI
Scala
122
star
28

sbt-projectmatrix

Scala
116
star
29

sbt-boilerplate

sbt plugin for generating scala.Tuple/Function related boilerplate code
Scala
110
star
30

sbt-proguard

Proguard sbt plugin
Scala
98
star
31

sbt-atmos

sbt plugin for running Typesafe Console in development
Scala
98
star
32

sbt-launcher-package

Packaging for sbt so you can run it.
Scala
90
star
33

sbt-dirty-money

clean Ivy2 cache
Scala
88
star
34

sbt-license-report

Report on licenses used in an sbt project.
Scala
86
star
35

sbt-doge

sbt plugin to aggregate tasks across subprojects and their crossScalaVersions
Scala
77
star
36

website

The source for scala-sbt.org
Scala
75
star
37

sbt-pom-reader

Translates xml -> awesome. Maven-ish support for sbt.
Scala
75
star
38

sbt-remote-control

Create and manage sbt process using unicorns and forks
Scala
74
star
39

sbt-aspectj

AspectJ sbt plugin
Scala
72
star
40

sbt-scalabuff

SBT plugin which generate case classes and support for serialization from Google Protocol Buffer definitions using ScalaBuff
Scala
72
star
41

contraband

http://www.scala-sbt.org/contraband/
Scala
67
star
42

sbt-s3

sbt-s3 is a simple sbt plugin to manipulate objects on Amazon S3
Scala
63
star
43

sbt-multi-jvm

Multi-JVM testing in sbt
Scala
56
star
44

sbt-javaagent

sbt plugin for adding java agents to projects
Scala
54
star
45

sbt-paradox-material-theme

Material Design theme for Paradox
StringTemplate
51
star
46

sbt-cpd

Copy & Paste Detector plugin using PMD for sbt.
Scala
48
star
47

sbt-osgi

sbt plugin for creating OSGi bundles
Scala
47
star
48

sbt-man

Looks up scaladoc.
Scala
46
star
49

librarymanagement

librarymanagement module for sbt
Scala
46
star
50

sbt-findbugs

FindBugs static analysis plugin for sbt.
Scala
46
star
51

sbt-less

Scala
42
star
52

ipcsocket

IPC: Unix Domain Socket and Windows Named Pipes for Java
Java
42
star
53

io

IO module for sbt
Scala
41
star
54

sbt-js-engine

Support for sbt plugins that use JavaScript
Scala
40
star
55

launcher

The sbt launcher as its own project. Can launch any ivy/maven published project with a main class, with some fancy features.
Scala
40
star
56

sbt-autoversion

Scala
36
star
57

sbt-avro

sbt plugin for compiling Avro schemas, similar to sbt-protobuf
Scala
32
star
58

sbt-digest

sbt-web plugin for checksum files
Scala
32
star
59

sbt-jupiter-interface

Implementation of SBT's test interface for JUnit Jupiter
Java
30
star
60

sbt-slash

unified slash syntax for both shell and build.sbt
Scala
29
star
61

sbt-java-formatter

An sbt plugin for formating Java code
Scala
28
star
62

sbt-gzip

sbt-web plugin for gzipping assets
Scala
25
star
63

sbt-unique-version

emulates Maven's uniqueVersion snapshots
Scala
24
star
64

sbt-pull-request-validator

Plugin that optimizes pull request validation to only validate sub projects that have changed
Scala
23
star
65

sbt.github.com

See https://github.com/sbt/website for the source
HTML
22
star
66

sbt-duplicates-finder

Find classes and resources conflicts in your build
Scala
22
star
67

sbt-autoplugin.g8

giter8 template for sbt 0.13.5+ AutoPlugin
Scala
20
star
68

sbt-cucumber

Cucumber plugin for SBT.
Scala
20
star
69

sbt-jcstress

Trust no-one, and especially not memory visibility.
HTML
19
star
70

adept

adept helps you find, declare, and download dependencies. http://groups.google.com/group/adept-dev/
18
star
71

sbt-sriracha

Scala
17
star
72

sbt-mocha

SBT plugin for running mocha JavaScript unit tests on node
Scala
17
star
73

sbt-multi-release-jar

Support for JDK9's Multi Release JAR Files (JEP 238)
Scala
17
star
74

sbt-xjc

SBT plugin to compile an XML Schema with XJC
Scala
15
star
75

util

util modules for sbt
Scala
15
star
76

sbt-export-repo

exports your dependency graph to a preloaded local repository
Scala
15
star
77

sbt-nocomma

sbt-nocomma reduces commas from your build.sbt.
Scala
13
star
78

serialization

serialization facility for sbt
Scala
13
star
79

sbt-maven-resolver

An sbt plugin to resolve dependencies using Aether
Scala
12
star
80

sbt-core-next

sbt APIs targeted for eventual inclusion in sbt core
Scala
12
star
81

sbt-houserules

House rules for sbt modules.
Scala
12
star
82

sbt-pamflet

sbt plugin to run Pamflet (and Pamflet plugin to run sbt)
Scala
11
star
83

sbt-sdlc

Scaladoc link checker for sbt
Scala
11
star
84

sbt-appbundle

A plugin for the simple-build-tool to create an OS X application bundle.
Scala
10
star
85

bintry

your packages, delivered fresh
Scala
10
star
86

sbt-fmpp

FreeMarker Scala/Java Templating Plugin for SBT
Scala
9
star
87

sbt-ynolub

Scala
9
star
88

sbt-testng

Implementation of the sbt testing interface for TestNG, bundled with an sbt plug-in for convenience.
Scala
9
star
89

sbt-concat

sbt-web plugin for concatenating web assets
Scala
8
star
90

sbt-ant

SBT plug-in to call Ant targets from within SBT builds
Scala
7
star
91

sbtn-dist

Shell
6
star
92

sbt-community-plugins

All community plugins that opt into an uber-build
Scala
6
star
93

sbt-vimquit

an sbt plugin that adds :q command.
Scala
5
star
94

helloworld-one

An example build for sbt 1.0.0.
Scala
5
star
95

sbt-giter8-resolver

Scala
5
star
96

sbt-sequential

adds sequential tasks to sbt
Scala
4
star
97

sbt-scalashim

generates sys.error.
Scala
4
star
98

sbt-experimental

Experimental APIs to fix rough edges in sbt
Scala
3
star
99

sbt-web-build-base

Scala
3
star
100

sbt-validator

Builds sbt 1.0.x against recent versions of the sbt modules
Shell
3
star