Add License Headers to Your Code Files

Introduction

As developers, we often need to ensure that our code complies with the appropriate licenses to protect our intellectual property.

This article introduces a more powerful license statement management tool called NWA. It helps you effortlessly add license headers to your code files and also check, update, and remove existing license statements, ensuring the legality and compliance of your code.

What Is a License Statement?

A license statement (license header) is a comment section at the top of a source code file that declares the licensing information for the code. It typically includes copyright information, license type, and other relevant legal statements. License statements help protect the rights of the code's author and also help other developers understand how they can use the code.

If you've ever looked at code files from open-source projects, you've probably noticed that they clearly mark their license statements within the code files. For example:

• kubernetes

• spring-boot

Additionally, some open-source projects use tools like GitHub Actions to check if your code has the correct license header when you submit a pull request:

• hertz

License Header Adding Tools

Usually, we need to display license statements in the form of comments at the beginning of each code file, similar to what 'kubernetes' and 'spring-boot' did in the previous section. However, when you are working on a large project, the number of code files can become extensive, making manually adding license headers a tedious and painful task.

This is where license header adding tools come in handy. One commonly used tool is the addlicense project under the 'google' organization. 'addlicense' allows you to add license statements to specified files via command-line interaction. However, 'addlicense' has limited functionality; it only adds license headers to files. Some issues raised for 'addlicense' include:

• Request for support for line comments (//) instead of only block comments (/**/) #130
• Request to add a feature for updating license statements #58
• Request for customizable license statement checking logic #56

Unfortunately, issue #58 is not supported due to concerns about adding complexity to 'addlicense', issue #130 is marked as unsupported, and issue #56 is currently awaiting review.

NWA's development took these issues into consideration and provided solutions. It also supports more operations related to license statements, such as removal. You can see how NWA addresses these issues and get started quickly in the Usage section.

Installation

Installation via Go (if you have Go installed)

go install github.com/B1NARY-GR0UP/nwa@latest

Execute the following command to verify a successful installation:

nwa --version

Installation via Docker (if you don't have Go installed)

1. Installation

Get NWA's Docker image directly:

docker pull ghcr.io/b1nary-gr0up/nwa:main

Alternatively, you can build the image from source, for example:

docker build -t ghcr.io/b1nary-gr0up/nwa:main .

1. Verify Installation

docker run -it ghcr.io/b1nary-gr0up/nwa:main --version

1. Mount the directory you want NWA to operate on to /src. Here's an example, but you can learn more about NWA's usage in the Usage section:

docker run -it -v ${PWD}:/src ghcr.io/b1nary-gr0up/nwa:main add -c "RHINE LAB.LLC." -y 2077 .

Usage

To help you get started with NWA's functionality, developers have provided nwa-examples to help you learn how to use NWA in a practical way. You can clone this project and follow the tutorial or simply refer to this guide and use nwa-examples for more usage examples.

NWA is a command-line tool built on cobra. Here's an overview of NWA's commands:

Usage:         
  nwa [command]

Common Mode Commands:
  add         add license headers to files
  check       check license headers of files
  remove      remove license headers of files
  update      update license headers of files

Config Mode Commands:
  config      edit the files according to the configuration file

Additional Commands:
  help        Help about any command

Flags:
  -h, --help      help for nwa
  -v, --version   version for nwa

Use "nwa [command] --help" for more information about a command.

Command List:

• Add: Add license headers to files.
• Remove: Remove license headers from files.
• Update: Update license headers in files.
• Check: Check license headers in files.
• Config: Edit license headers in files using a configuration file.

Add - Add License Headers to Files

Usage

nwa add [flags] path...

Use the add command after nwa to add license headers. [flags] allows you to specify optional flags, and path... lets you specify one or more file paths to add license headers to.

Example

nwa add -l apache -c "RHINE LAB.LLC." -y 2077 ./server ./utils/bufferpool

In the above example, the command adds the following to all files in the relative paths ./server and ./utils/bufferpool:

• License type: Apache 2.0
• Copyright holder: RHINE LAB.LLC.
• Copyright year: 2077

NWA generates the corresponding license statement for each file based on its type, e.g., .py files use # comments, and .go files use // comments. If your file type is not supported by NWA, you can:

• Specify a template file using the -t (--tmpl) flag.
• Contribute to NWA by creating an issue or pull request.

NWA will also provide log

outputs indicating files that already have license headers or are not allowed for editing (such as some generated code files).

Flags

The add command supports the following flags:

Short Flag	Long Flag	Default	Description
-c	--copyright	<COPYRIGHT HOLDER>	Copyright holder
-l	--license	apache	License type
-m	--mute	false (unspecified)	Mute mode
-s	--skip	[]	Skipped file paths
-t	--tmpl	""	Template file path
-y	--year	time.Now().Year() (current year)	Copyright year
-h	--help	None	Help

Most flags are self-explanatory. Notable flags are -s (-skip) and -t (-tmpl):

• -s's default value is an empty array, so you can use zero or more -s flags to specify file paths to skip. This path supports doublestar syntax, making it very flexible. For example:

nwa add -s **.py -s /example/**/*.txt -c Lorain .

• -t allows you to specify a template file path. NWA reads the content of this template file and adds its content to the files that require license headers.

Note: If you specify a template, NWA won't generate license headers based on file types, and it will ignore -c, -l, and -y configurations.

Here's an example of a template file (example-tmpl.txt):

// Copyright 2077 RHINE LAB.LLC.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

For more usage examples, refer to nwa-examples.

Remove - Remove License Headers from Files

Usage

nwa remove [flags] path...

Use the remove command after nwa to remove license headers. [flags] allows you to specify optional flags, and path... lets you specify one or more file paths to remove license headers from.

Example

nwa remove -l mit -c "RHINE LAB.LLC." -s **.py pkg

In the above example, the command removes the following from all non-Python files in the relative path pkg:

• License type: MIT
• Copyright holder: RHINE LAB.LLC.
• Copyright year: 2023

NWA provides log outputs indicating files without license headers or files that are not editable.

Flags

The remove command supports the following flags:

Short Flag	Long Flag	Default	Description
-c	--copyright	<COPYRIGHT HOLDER>	Copyright holder
-l	--license	apache	License type
-m	--mute	false (unspecified)	Mute mode
-s	--skip	[]	Skipped file paths
-t	--tmpl	""	Template file path
-y	--year	time.Now().Year() (current year)	Copyright year
-h	--help	None	Help

Note: If you specify a template, NWA won't generate license headers based on file types, and it will ignore -c, -l, and -y configurations.

For more usage examples, refer to nwa-examples.

Update - Update License Headers in Files

Usage

nwa update [flags] path...

Use the update command after nwa to update license headers. [flags] allows you to specify optional flags, and path... lets you specify one or more file paths to update license headers in.

Example

nwa update -l apache -c "BINARY Members" .

In the above example, the command updates the license headers in all files in the current path with the following:

• License type: Apache 2.0
• Copyright holder: BINARY Members
• Copyright year: 2023

The previous copyright statement is replaced, regardless of its content.

Note: Update is essentially a combination of Remove and Add operations.

The update command recognizes the content before the first empty line in a file as the license header (with the exception of shebang lines). NWA generates a new license statement based on the specified flags and replaces the existing one.

If the content before the first empty line in your file includes something other than the license statement, it's recommended to use the remove and add operations separately to achieve the same effect. This approach, along with the template file flag, can lead to better removal results in the remove operation.

Flags

The update command supports the following flags:

Short Flag	Long Flag	Default	Description
-c	--copyright	<COPYRIGHT HOLDER>	Copyright holder
-l	--license	apache	License type
-m	--mute	false (unspecified)	Mute mode
-s	--skip	[]	Skipped file paths
-t	--tmpl	""	Template file path
-y	--year	time.Now().Year() (current year)	Copyright year
-h	--help	None	Help

Note: If you specify a template, NWA won't generate license headers based on file types, and it will ignore -c, -l, and -y configurations.

For more usage examples, refer to nwa-examples.

Check - Check License Headers in Files

Usage

nwa check [flags] path...

Use the check command after nwa to check license headers. [flags] allows you to specify optional flags, and path... lets you specify one or more file paths to check license headers in.

Example

nwa check --tmpl tmpl.txt ./client

In the above example, the command checks if license headers in all files within the ./client folder match the content specified in the tmpl.txt template file.

After checking, NWA provides log outputs indicating the result of the check. Here's a sample output:

time="2023-08-25T23:01:49+08:00" level=info msg="skip file" path=README.md
time="2023-08-25T23:01:49+08:00" level=info msg="file has a matched header" path="dirA\\fileA.go"                
time="2023-08-25T23:01:49+08:00" level=info msg="file does not have a matched header" path="dirB\\dirC\\fileC.go"
time="2023-08-25T23:01:49+08:00" level=info msg="file has a matched header" path="dirB\\fileB.go"                
time="2023-08-25T23:01:49+08:00" level=info msg="file does not have a matched header" path=main.go 

Flags

The check command supports the following flags:

Short Flag	Long Flag	Default	Description
-c	--copyright	<COPYRIGHT HOLDER>	Copyright holder
-l	--license	apache	License type
-m	--mute	false (unspecified)	Mute mode
-s	--skip	[]	Skipped file paths
-t	--tmpl	""	Template file path
-y	--year	time.Now().Year() (current year)	Copyright year
-h	--help	None	Help

Note: Avoid using the -m flag with the check command, as it will prevent NWA from outputting the check results.

For more usage examples, refer to nwa-examples.

Config - Edit License Headers via Configuration File

Usage

nwa config [flags] path

Use the config command after nwa to edit license headers based on a configuration file. [flags] allows you to specify optional flags, and path is required to specify the path to the configuration file.

Example

nwa config config.yaml

In the above example, the command reads the config.yaml configuration file and edits license headers in specified files according to its content. The structure of the configuration file is provided below.

Flags

Since all configuration is in the configuration file, there's only one help flag.

Short Flag	Long Flag	Default	Description
-h	--help	None	Help

Configuration File

Here's an example of a complete configuration file (config.yaml):

nwa:
  cmd: "add"                        # Default: "add". Options: "add", "check", "remove", "update"
  holder: "RHINE LAB.LLC."          # Default: "<COPYRIGHT HOLDER>"
  year: "2077"                      # Default: Current Year
  license: "apache"                 # Default: "apache"
  mute: false                       # Default: false (unspecified)
  path: ["server", "client", "pkg"] # Default: []
  skip: ["**.py"]                   # Default: []
  tmpl: "nwa.txt"                   # Default: ""

If you don't specify certain fields in the configuration file, NWA will use default values. For example, if you don't specify the license type, Apache 2.0 will be used by default.

Note: If you set the tmpl field, NWA will ignore the holder, year, and license fields.

For more usage examples, refer to nwa-examples.

Conclusion

The above content introduces NWA — A Powerful License Header Management Tool.

If you find this tool helpful, please consider giving our project a star!

If you notice any errors or have questions, feel free to leave a comment or send a message.

References

• https://github.com/B1NARY-GR0UP/nwa
• https://github.com/rainiring/nwa-examples
• https://github.com/google/addlicense
• https://github.com/bmatcuk/doublestar
• https://github.com/spf13/cobra

Comments

[Phil Ashby]

Thank you for this tool, it's always good to have a choice 😁

Recently I've adopted the SPDX short form licence ID in my source code, following the Linux kernel team and other high-profile projects. What are your thoughts on SPDX?

[Lorain]

I have just read the SPDX link you provided, and I think SPDX IDs are a more flexible, straightforward, and efficient approach compared to license headers. Currently, it seems that NWA can only add SPDX IDs to each code file through custom templates. In the next version, I will include an option and template for built-in SPDX support in NWA : )

[Lorain]

Hi! NWA 0.2.0 is released and supports spdxids, welcome to experience it : )

[Casper]

REUSE Software also has a tool like this, and it uses SPDX format. This is an initiative driven by the Free Software Foundation to make it easy to figure out what licenses are used in a project. You can easily check if you are compliant with their standard, and you can get a list of the licenses of all files. It supports dual-licensed and multi-licensed files.

The goal is not just to make sure that your project is fully licensed, but that others viewing and using that code can easily figure out how they can use it. I highly encourage following this standard.

[Lorain]

Thanks for sharing!