{"id":13648883,"url":"https://github.com/sbt/sbt-header","last_synced_at":"2025-04-09T15:01:59.081Z","repository":{"id":26903765,"uuid":"30365481","full_name":"sbt/sbt-header","owner":"sbt","description":"sbt-header is an sbt plugin for creating file headers, e.g. copyright headers","archived":false,"fork":false,"pushed_at":"2024-08-13T03:15:45.000Z","size":1432,"stargazers_count":186,"open_issues_count":23,"forks_count":57,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-02T13:01:52.776Z","etag":null,"topics":["license","sbt-plugin"],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-05T16:25:45.000Z","updated_at":"2024-10-28T16:29:46.000Z","dependencies_parsed_at":"2024-06-20T02:59:17.846Z","dependency_job_id":"330a97fc-7784-4558-887d-93e4505917e3","html_url":"https://github.com/sbt/sbt-header","commit_stats":null,"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-header","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-header/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-header/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-header/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbt","download_url":"https://codeload.github.com/sbt/sbt-header/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248055272,"owners_count":21040153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["license","sbt-plugin"],"created_at":"2024-08-02T01:04:37.447Z","updated_at":"2025-04-09T15:01:59.058Z","avatar_url":"https://github.com/sbt.png","language":"Scala","readme":"# sbt-header #\n\n[![License](http://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)\n\nsbt-header is an [sbt](http://www.scala-sbt.org) plugin for creating or updating file headers, e.g. copyright headers.\n\n## Getting started\n\nIn order to add the sbt-header plugin to your build, add the following line to `project/plugins.sbt`:\n\n``` scala\naddSbtPlugin(\"de.heikoseeberger\" % \"sbt-header\" % \"5.6.0\") // Check the latest version above or look at the release tags\n```\n\nThen in your `build.sbt` configure the following settings:\n\n```scala\norganizationName := \"Heiko Seeberger\"\nstartYear := Some(2015)\nlicenses += (\"Apache-2.0\", new URL(\"https://www.apache.org/licenses/LICENSE-2.0.txt\"))\n```\n\nThis 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](#configuration) section.\n\n### Creating headers\n\nIn order to create or update file headers, execute the `headerCreate` task:\n\n```\n\u003e headerCreate\n[info] Headers created for 2 files:\n[info]   /Users/heiko/projects/sbt-header/sbt-header-test/test.scala\n[info]   /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala\n```\n\nThe task is incremental, meaning that it will not look at files that have not seen changes since\nthe last time the task was run.\n\n\n### Checking headers\n\nIn order to check whether all files have headers (for example for CI), execute the `headerCheck` task:\n\n```\n\u003e headerCheck\n[error] (compile:checkHeaders) There are files without headers!\n[error]   /Users/heiko/projects/sbt-header/sbt-header-test/test.scala\n[error]   /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala\n```\n\n`headerCheck` will not modify any files but will cause the build to fail if there are files without a license header.\n\n### Requirements\n\n- Java 8 or higher\n- sbt 1.0.0 or higher\n\n## Configuration\n\nBy 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](http://spdx.org/licenses/) of one of the [supported licenses](#build-in-licenses).\n\n### Setting the license to use explicitly\n\nIf 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:\n\n```scala\nheaderLicense := Some(HeaderLicense.MIT(\"2015\", \"Heiko Seeberger\"))\n```\n\nThis will also be given precedence if a license has been auto detected from project settings.\n\n### Build in licenses\n\nThe most common licenses have been pre-canned in [License](https://github.com/sbt/sbt-header/blob/master/src/main/scala/de/heikoseeberger/sbtheader/License.scala). They can either be detected using their SPDX identifier or by setting them explicitly.\n\n|License|SPDX identifier|\n|-------|---------------|\n|[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)|`Apache-2.0`|\n|[BSD 2 Clause](https://opensource.org/licenses/BSD-2-Clause)|`BSD-2-Clause`|\n|[BSD 3 Clause](https://opensource.org/licenses/BSD-3-Clause)|`BSD-3-Clause`|\n|[GNU General Public License v3 or later](https://spdx.org/licenses/GPL-3.0-or-later.html)|`GPL-3.0-or-later`|\n|[GNU General Public License v3 only](https://spdx.org/licenses/GPL-3.0-only.html)|`GPL-3.0-only`|\n|[GNU General Public License v3 (deprecated)](https://spdx.org/licenses/GPL-3.0.html)|`GPL-3.0`|\n|[GNU Lesser General Public License v3 or later](https://spdx.org/licenses/LGPL-3.0-or-later.html)|`LGPL-3.0-or-later`|\n|[GNU Lesser General Public License v3 only](https://spdx.org/licenses/LGPL-3.0-only.html)|`LGPL-3.0-only`|\n|[GNU Lesser General Public License v3 (deprecated)](https://spdx.org/licenses/LGPL-3.0.html)|`LGPL-3.0`|\n|[GNU Affero General Public License v3 or later](https://spdx.org/licenses/AGPL-3.0-or-later.html)|`AGPL-3.0-or-later`|\n|[GNU Affero General Public License v3 only](https://spdx.org/licenses/AGPL-3.0-only.html)|`AGPL-3.0-only`|\n|[GNU Affero General Public License v3 (deprecated)](https://spdx.org/licenses/AGPL-3.0.html)|`AGPL-3.0`|\n|[MIT License](https://opensource.org/licenses/MIT)|`MIT`|\n|[Mozilla Public License, v. 2.0](http://mozilla.org/MPL/2.0/)|`MPL-2.0`|\n\n### Using the short SPDX license identifier syntax\n\nIf you want to use the following syntax:\n```\n  /*\n   * Copyright 2015 Heiko Seeberger\n   *\n   * SPDX-License-Identifier: BSD-3-Clause\n   */\n```\n\nYou have two possibilites:\n\n- If you are using auto-detection, you just need to add the following to your `build.sbt`\n\n```sbt\nheaderLicenseStyle := HeaderLicenseStyle.SpdxSyntax\n```\n\n- On the other hand, if you are defining your license explicitly, you'll have to pass the style when defining the `headerLicense` attribute:\n\n```scala\nheaderLicense := Some(HeaderLicense.MIT(\"2015\", \"Heiko Seeberger\", HeaderLicenseStyle.SpdxSyntax))\n```\n\n### Using a custom license text\n\nIf you don't want to use one of the built-in licenses, you can define a custom license text using the `Custom` case class:\n\n```scala\nheaderLicense := Some(HeaderLicense.Custom(\n  \"\"\"|Copyright (c) Awesome Company 2015\n     |\n     |This is the custom License of Awesome Company\n     |\"\"\".stripMargin\n))\n```\n\nNote 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)).\n\n### Configuring comment styles\n\nComment 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](https://github.com/sbt/sbt-header/blob/master/src/main/scala/de/heikoseeberger/sbtheader/CommentStyle.scala):\n\n|Name|Description|\n|----|-----------|\n|cStyleBlockComment|C style block comments (blocks starting with \"/\\*\" and ending with \"\\*/\")|\n|cppStyleLineComment|C++ style line comments (lines prefixed with \"//\")|\n|hashLineComment|Hash line comments (lines prefixed with \"#\")|\n|twirlStyleComment|Twirl style comment (blocks starting with \"@\\*\" and ending with \"\\*@\")|\n|twirlStyleBlockComment|Twirl style block comments (comment blocks with a frame made of \"*\")|\n\nTo override the configuration for Scala/Java files or add a configuration for some other file type, use the `headerMapping` setting:\n\n``` scala\nheaderMappings := headerMappings.value + (HeaderFileType.scala -\u003e HeaderCommentStyle.cppStyleLineComment)\n```\n\n#### Custom comment creators\n\nYou can customize how content gets created by providing your own\n`CommentCreator`. For example, this would be a (crude) way to preserve the\ncopyright year in existing headers but still update the rest:\n\n    CommentStyle.cStyleBlockComment.copy(commentCreator = new CommentCreator() {\n      val Pattern = \"(?s).*?(\\\\d{4}(-\\\\d{4})?).*\".r\n      def findYear(header: String): Option[String] = header match {\n       case Pattern(years, _) =\u003e Some(years)\n        case _                 =\u003e None\n      }\n      override def apply(text: String, existingText: Option[String]): String = {\n        val newText = CommentStyle.cStyleBlockComment.commentCreator.apply(text, existingText)\n        existingText\n          .flatMap(findYear)\n          .map(year =\u003e newText.replace(\"2017\", year))\n          .getOrElse(newText)\n      }\n    })\n\n### Excluding files\n\nTo exclude some files, use the [sbt's file filters](http://www.scala-sbt.org/0.13/docs/Howto-Customizing-Paths.html#Include%2Fexclude+files+in+the+source+directory):\n\n``` scala\nexcludeFilter.in(headerSources) := HiddenFileFilter || \"*Excluded.scala\"\nexcludeFilter.in(headerResources) := HiddenFileFilter || \"*.xml\"\n```\n\n### Empty line between header and body\n\nIf an empty line header should be added between the header and the body of a file (defaults to `true`):\n\n```scala\nheaderEmptyLine := false\n```\n\n### Using an auto plugin\n\nIf your build uses an auto plugin for common settings, make sure to add `HeaderPlugin` to `requires`:\n\n``` scala\nimport de.heikoseeberger.sbtheader.HeaderPlugin\n\nobject Build extends AutoPlugin {\n  override def requires = ... \u0026\u0026 HeaderPlugin\n  ...\n}\n```\n\n### Adding headers to files in other configurations\n\nBy default sbt-header takes `Compile` and `Test` configurations into account. If you need more, just add them:\n\n``` scala\nheaderSettings(It, MultiJvm)\n```\n\n### Automation\n\nIf you want to automate header creation/update on compile, enable the `AutomateHeaderPlugin`:\n\n``` scala\nlazy val myProject = project\n  .in(file(\".\"))\n  .enablePlugins(AutomateHeaderPlugin)\n```\n\nBy default automation takes `Compile` and `Test` configurations into account. If you need more, just add them:\n\n``` scala\nautomateHeaderSettings(It, MultiJvm)\n```\n\n## Integration with other plugins\n\nThis plugin by default only handles `managedSources` and `managedResources` in `Compile` and `Test`. For this reason you\nneed to tell sbt-header if it should also add headers to additional files managed by other plugins.\n\n### sbt-twirl / play projects\n\nTo use sbt-header in a project using [sbt-twirl](https://github.com/playframework/twirl) (for example a Play web\nproject), the Twirl templates have to be added to the sources handled by sbt-header. Add the following to your build\ndefinition:\n\n```scala\nimport de.heikoseeberger.sbtheader.FileType\nimport play.twirl.sbt.Import.TwirlKeys\n\nheaderMappings := headerMappings.value + (FileType(\"html\") -\u003e HeaderCommentStyle.twirlStyleBlockComment)\n\nheaderSources.in(Compile) ++= sources.in(Compile, TwirlKeys.compileTemplates).value\n```\n\nsbt-header supports two comment styles for Twirl templates. `twirlStyleBlockComment` will produce simple twirl block comments, while `twirlStyleFramedBlockComment` will produce\nframed twirl comments.\n\n`twirlStyleBlockComment` comment style:\n\n```scala\n@*\n * This is a simple twirl block comment\n *@\n```\n\n`twirlStyleFramedBlockComment` comment style:\n\n```scala\n@**********************************\n * This is a framed twirl comment *\n **********************************@\n```\n\n### sbt-boilerplate\n\nIn order to use sbt-header with [sbt-boilerplate plugin](https://github.com/sbt/sbt-boilerplate) add the following to\nyour build definition:\n\n```scala\ndef addBoilerplate(confs: Configuration*) = confs.foldLeft(List.empty[Setting[_]]) { (acc, conf) =\u003e\n  acc ++ Seq(\n    headerSources in conf ++= (((sourceDirectory in conf).value / \"boilerplate\") ** \"*.template\").get),\n    headerMappings        += (FileType(\"template\") -\u003e HeaderCommentStyle.cStyleBlockComment)\n  )\n}\n\naddBoilerplate(Compile, Test)\n```\n\nThis adds `src/{conf}/boilerplate/**.scala` in the list of files handled by sbt-headers for `conf`, where `conf` is\neither `Compile` or `Test`.\n\n## Migrating from 1.x\n\nThis 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](https://github.com/sbt/sbt-header/tree/v1.8.0).\n\n### Changed task names and settings keys\n\nThe 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:\n\nChanged task names:\n\n|Old Name|New Name|\n|--------|--------|\n|`createHeaders`|`headerCreate`|\n|`checkHeaders`|`headerCheck`|\n\nChanged settings:\n\n|Old Name : Old Type|New Name: New Type|\n|--------|--------|\n|`headers : Map[String, (Regex, String)]`|`headerMappings : Map[FileType, CommentStyle]`|\n| - | `headerLicense : Option[License]`|\n| `exclude : Seq[String]` | removed in favor of sbt include/excude filters|\n\n### `createFrom` method\n\nsbt-header 1.x featured some default header mappings as well as the `createFrom` method, which could be used to easily define header mappings:\n\n```scala\nheaders := createFrom(Apache2_0, \"2015\", \"Heiko Seeberger\")\n```\n\nThis method has been removed and the default mappings for Scala and Java files has been added as default mapping to the `headerMappings` setting.\n\n### Custom licenses\n\nIn sbt-header 1.x when you needed to use a custom license this would typically look like this:\n\n```scala\nheaders := Map(\n  \"scala\" -\u003e (\n    HeaderPattern.cStyleBlockComment,\n    \"\"\"|/*\n       | * Copyright 2015 Awesome Company\n       | */\n       |\"\"\".stripMargin\n  )\n)\n```\n\nIn 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:\n\n```scala\nheaderLicense := Some(HeaderLicense.Custom(\n    \"\"\"|Copyright 2015 Awesome Company\n       |\"\"\".stripMargin\n))\n```\n\nNote 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.\n\n### Dropped features\n\nIn sbt-header 1.x it was possible to define different licenses for different files types, e.g.:\n\n```scala\nheaders := Map(\n  \"scala\" -\u003e Apache2_0(\"2015\", \"Heiko Seeberger\"),\n  \"java\" -\u003e MIT(\"2015\", \"Heiko Seeberger\")\n)\n```\n\nSince 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](#getting-started)) and a mapping from file type to comment style using the `headerMappings` setting.\n\n## Contribution policy ##\n\nContributions 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.\n\n## License ##\n\nThis code is open source software licensed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html).\n","funding_links":[],"categories":["Scala","Table of Contents","Sbt plugins"],"sub_categories":["Sbt plugins"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-header","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbt%2Fsbt-header","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-header/lists"}