A More Powerful License Header Management Tool

English | 中文

Install

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

Do not have a Go environment? Check the Docker section.

Usage

• Add: Add license headers to files
• Check: Check license headers of files
• Remove: Remove licenses headers of files
• Update: Update license headers of files
• Config: Edit files according to the configuration file
• Supported Licence Templates: Use built-in license templates or use custom templates
• Docker: Run NWA through docker, for those do not have a Go environment
• Used In CI: Use NWA in CI
• Examples: Examples of NWA usage

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.

Common Mode

Flags

Short	Long	Default	Description
-c	--copyright	<COPYRIGHT HOLDER>	copyright holder
-l	--license	apache	license type
-i	--spdxids	""	SPDX IDs
-m	--mute	false (unspecified)	mute mode
-s	--skip	[]	skip file paths, can use any pattern supported by doublestar
-t	--tmpl	""	template file path
-r	--rawtmpl	""	template file path (enable raw template)
-y	--year	time.Now().Year() (Current Year)	copyright year
-h	--help	null	help for command

Add - Add license headers to files

• Usage

nwa add [flags] path...

• Example

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

The command in the example above adds a license header to all files under the folders with relative paths ./server and ./utils/bufferpool:

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

NWA will generate a corresponding license header based on the file type in the specified paths. For example, .py files will use # for comments, and .go files will use //.

If your file type is not supported by NWA, you can:

• Specify a custom template file using the --tmpl (-t) or --rawtmpl (-r) flag. Refer to Supported Licence Templates
• Submit an issue or PR to NWA

NWA will also output logs to inform you if any files already have a license header or if any files are not allowed to be edited (such as code files generated by tools).

Check - Check license headers of files

• Usage

nwa check [flags] path...

NOTE: Do not use --mute (-m) flag with check command.

• Example

nwa check --tmpl tmpl.txt ./client

The command in the example above checks whether the license header of all files under the folder with the relative path ./client match the content specified in the tmpl.txt template file.

After the check is complete, NWA will output the results as logs. A sample output is as follows:

2024/10/27 20:38:57 INFO skip file path=README.md
2024/10/27 20:38:57 INFO file has a matched header path=dirA\fileA.go
2024/10/27 20:38:57 INFO file has a matched header path=dirB\fileB.go
2024/10/27 20:38:57 INFO file does not have a matched header path=main.go
2024/10/27 20:38:57 INFO file does not have a matched header path=dirB\dirC\fileC.go
2024/10/27 20:38:57 INFO Summary matched=2 mismatched=2 skipped=1 failed=0

Remove - Remove licenses headers of files

• Usage

nwa remove [flags] path...

• Example

nwa remove -l mit -c "RHINE LAB.LLC." -s "vender/**" src

The command in the example above skips all files under the vendor folder and removes the license header for files under the folder with the relative path src:

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

If a file in the specified path does not have a license header or is not allowed to be edited, NWA will inform you through log output.

Update - Update license headers of files

• Usage

nwa update [flags] path...

NOTE: Update identifies the content before the first blank line as a license header; If your file does not meet the requirements, please use remove + add command.

• Example

nwa update -l apache -c "BINARY Members" -s "dirA/**" -s "dirB/*.py" .

The command in the example above updates the license header of all files in the current directory, except for all files under dirA and Python files under dirB, to:

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

regardless of the previous license header.

Config Mode

• Flags

Short	Long	Default	Description
-h	--help	null	help for config

NOTE: If some configuration are not configured, the default configuration will be used.

• Usage

nwa config [flags] path

NOTE: Path is the configuration file path.

• Example

nwa config config.yaml

The command in the example above reads the config.yaml configuration file and edits the license header of the specified files according to its content. The structure of the configuration file will be provided below.

• Sample Configuration file

NOTE: If you set the tmpl or rawtmpl field, the holder, year, license and spdxids fields will be ignored.

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

Supported Licence Templates

License	Option (ignore case)
Apache-2.0	apache, apache-2.0, apache-2, apache 2.0, apache2.0
MIT	mit
GPL-3.0 or Later	gpl-3.0-or-later
GPL-3.0 Only	gpl-3.0-only
AGPL-3.0 or Later	agpl-3.0-or-later
AGPL-3.0 Only	agpl-3.0-only

If the license template you need is not available, you could use the --tmpl (-t) flag, --rawtmpl (-r) flag or submit an Issue/PR.

NOTE: The --tmpl (-t) and --rawtmpl (-r) flags cannot be used simultaneously.

--tmpl (-t)

• Example

nwa add -t mytmpl.txt .

mytmpl.txt is as follows:

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.

This command example uses the content in mytmpl.txt as the license header, and NWA will generate license headers with different comment types based on the file type.

--rawtmpl (-r)

If you want to use the content of the template file directly to the header of your file without modification, please use the -rawtmpl (-r) flag. When the raw template is enabled, NWA will not generate different types of licence headers based on your file type.

• Example

nwa add --rawtmpl myrawtmpl.txt .

myrawtmpl.txt is as follows:

// 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.

This command example uses the content in myrawtmpl.txt as the license header. NWA will not generate license headers with different comment types based on the file type but will instead add the content of myrawtmpl.txt directly to each file (include blank line).

Docker - Run NWA through docker, for those do not have a Go environment

• Install

Install the nwa docker image directly:

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

OR

Build it from source:

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

• Verify if it can work correctly

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

• Mount the directory you want NWA to work with to /src and use the commands mentions in usage

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

Used in CI

• GitHub Action Example

When there are mismatched or failed entries in the result of nwa check, nwa will return a non-zero exit code, causing the CI to fail.

You may refer to the other commands or flags introduced in the "Usage" section for optimization.

name: Pull Request Check

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Go
        uses: actions/setup-go@v3
        with:
          go-version: 1.21

      - name: Install NWA
        run: go install github.com/B1NARY-GR0UP/nwa@latest

      - name: Run License Header Check
        run: nwa check -c "BINARY Members" -l apache ./**/*.go ./*.go

Related Projects

• nwa-examples: Examples of NWA functionality

Blogs

• Add License Headers to Your Code Files

Credits

Sincere appreciation to the following repositories that made the development of NWA possible.

• addlicense
• cobra
• doublestar
• viper

License

NWA is distributed under the Apache License 2.0. The licenses of third party dependencies of NWA are explained here.

ECOLOGY

NWA is a Subproject of the Basic Middleware Service