likes
comments
collection
share

为您的代码文件添加许可声明：NWA一款更强大的许可声明管理工具

作者站长头像
站长
· 阅读数 62

前言

作为开发者，我们经常需要确保我们的代码遵循合适的许可证，并以此来保护我们的知识产权。

本文将介绍一款更强大的许可声明管理工具 —— NWA，它可以帮助您轻松地为代码文件 添加 许可声明（license header）并对已有的许可声明进行 检查，更新 和 删除，确保您的代码的合法使用和合规性。

什么是许可声明

许可声明（license header）是指在源代码文件的顶部包含的一段注释，用于声明代码的许可证信息。通常包括了代码的版权信息、许可证类型以及其他相关的法律声明。许可声明有助于确保代码作者的权益得到保护，同时也帮助其他开发人员了解他们可以如何使用这些代码。

如果你查看过一些开源项目的代码文件，你就能发现他们在代码文件中都很好的标示了自己的许可声明：

  • kubernetes

为您的代码文件添加许可声明：NWA一款更强大的许可声明管理工具

  • spring-boot

为您的代码文件添加许可声明：NWA一款更强大的许可声明管理工具

并且一些开源项目会以例如 GitHub Action 的形式在你通过 PR 提交代码时检查的你的代码是否具有正确的许可声明：

  • hertz

为您的代码文件添加许可声明：NWA一款更强大的许可声明管理工具

许可声明添加工具

通常我们需要在每一个代码文件的头部都通过注释的形式来展示你的许可声明，就如你在上一节的例子中 kubernetes 和 spring-boot 做的那样。但是当你在编写一个庞大的项目时，代码文件的数量会变得很多，这时手动的为每一个代码文件添加许可声明就会变成一种 繁琐且痛苦 的事情。

所以这时就需要通过许可声明添加工具来帮助你完成这件事情，目前一个常用的许可声明添加工具是位于 google 组织下的 addlicense 项目；addlicense 通过命令行交互的方式可以为指定的文件添加对应的许可声明。但是 addlicense 的功能比较局限，只有为文件添加许可声明这一个功能，我查看了 addlicense 的 issues 反应的一些问题并列举如下：

  • 希望支持行注释（//）而不是只能使用块注释（/**/） #130
  • 希望增加许可声明的更新功能 #58
  • 希望可以自定义许可声明的检查逻辑 #56

但是遗憾的是对于 #58 作者由于担心会增加 addlicense 的复杂度并不支持添加，#130 作者表示不会支持，#56 目前无人审查 PR。

NWA 的开发参考了这些问题并很好的给出了解决方案，同时支持了更多的对许可声明的操作（比如删除），您可以在 使用 章节看到 NWA 是如何解决这些问题的以及 NWA 的快速入门。

安装

通过 Go 安装（如果您有 Go 环境）

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

执行以下命令以验证是否安装成功：

nwa --version

通过 Docker 安装（如果您没有 Go 环境）

  1. 安装

直接获取 NWA 的 docker 镜像：

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

或者自己从源码构建镜像，示例：

docker build -t ghcr.io/b1nary-gr0up/nwa:main .
  1. 验证是否安装成功
docker run -it ghcr.io/b1nary-gr0up/nwa:main --version
  1. 将希望让 NWA 进行操作的目录挂载到 /src 目录下，以下是一个示例，您可以通过阅读 使用 章节了解 NWA 的用法后再来体验：
docker run -it -v ${PWD}:/src ghcr.io/b1nary-gr0up/nwa:main add -c "RHINE LAB.LLC." -y 2077 .

使用

为了帮助您更好的上手 NWA 的功能使用，开发者提供了 nwa-examples 来帮助您以实践的方式学习 NWA 的使用。您可以 clone 这个项目并结合这个教程一起食用或者也可以直接查看本教程，并通过 nwa-example 来获取更多的使用示例。

NWA 是一个基于 cobra 搭建的命令行工具，以下是 NWA 的命令总览：

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.

命令列表

  • Add: 为文件添加许可声明；
  • Remove: 移除文件的许可声明；
  • Update: 更新文件的许可声明；
  • Check: 检查文件的许可声明；
  • Config: 以配置文件的方式编辑文件的许可声明；

Add - 为文件添加许可声明

使用

nwa add [flags] path...

通过在 nwa 后面指定 add 命令来执行添加许可声明的操作，[flags] 表示可以添加 0 个或多个可选的 flag，path... 表示您可以指定一个或多个要添加许可声明的文件的路径。

使用示例

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

以上示例的命令表示为相对路径为 ./server 和 ./utils/bufferpool 文件夹下的所有文件添加

  • 许可证类型： Apache 2.0

  • 版权归属（copyright holder）： RHINE LAB.LLC.

  • 版权年份： 2077

的许可声明。

并且 NWA 会根据指定路径下的文件类型生成对应的许可声明，比如 .py 文件使用 # 注释，.go 文件使用 // 注释；

如果您的文件不在 NWA 内置的文件类型中，您可以：

  • 通过 -t（--tmpl）flag 指定模板文件；

  • 为 NWA 提一个 issue 或者 PR；

NWA 也会以输出日志的形式提示您如果有文件已经具有了许可声明或者是不被允许编辑的文件（例如一些工具生成的代码文件）。

Flags

add 命令目前支持的 flags 如下表所示：

短标志长标志默认值介绍
-c--copyright<COPYRIGHT HOLDER>版权归属
-l--licenseapache许可证类型
-m--mutefalse (不指定)静默模式
-s--skip[]跳过的文件路径
-t--tmpl""模板文件路径
-y--yeartime.Now().Year() (当前年份)版权年份
-h--help无帮助

大部分的 flag 都很容易理解，值得一提的是 -s （-skip）和 -t（-tmpl）;

  • -s 的默认值是一个空数组，所以您可以使用 0 个或多个 -s 来指定要跳过的文件路径，并且这个路径支持 doublestar 语法，所以非常灵活，比如可以这样使用：
nwa add -s **.py -s /example/**/*.txt -c Lorain .
  • -t 允许您指定一个模板文件的路径，NWA 会读取这个模板文件的内容并为要进行添加许可声明的文件添加上模板中所定义的内容；

注意：如果您指定了模板，则 NWA 不会根据文件类型生成对应的许可声明，而是对所有路径下的文件添加模板中的内容，指定了模板也会让 NWA 忽略通过 -c，-l 和 -y 指定的配置。

一个模板文件的示例如下：

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

更多的使用示例请您参考 nwa-examples。

Remove - 移除文件的许可声明

使用

nwa remove [flags] path...

通过在 nwa 后面指定 remove 命令来执行添加许可声明的操作，[flags] 表示可以添加 0 个或多个可选的 flag，path... 表示您可以指定一个或多个要移除许可声明的文件的路径。

使用示例

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

以上示例的命令表示为相对路径为 pkg 文件夹下的所有 非 Python 文件 移除

  • 许可证类型： MIT

  • 版权归属（copyright holder）： RHINE LAB.LLC.

  • 版权年份： 2023

的许可声明。

如果路径下的文件没有许可声明或者是不可进行编辑的文件，NWA 会以输出日志的形式提示您。

Flags

remove 命令目前支持的 flags 如下表所示：

短标志长标志默认值介绍
-c--copyright<COPYRIGHT HOLDER>版权归属
-l--licenseapache许可证类型
-m--mutefalse (不指定)静默模式
-s--skip[]跳过的文件路径
-t--tmpl""模板文件路径
-y--yeartime.Now().Year() (当前年份)版权年份
-h--help无帮助

注意：如果您指定了模板，则 NWA 不会根据文件类型来移除对应的许可声明，而是移除路径下所有符合模板文件内容的许可声明。

更多的使用示例请您参考 nwa-examples。

Update - 更新文件的许可声明

使用

nwa update [flags] path...

通过在 nwa 后面指定 update 命令来执行更新许可声明的操作，[flags] 表示可以添加 0 个或多个可选的 flag，path... 表示您可以指定一个或多个要更新许可声明的文件的路径。

使用示例

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

以上示例的命令表示将当前路径下的所有文件的许可声明 更新 为

  • 许可证类型： Apache 2.0

  • 版权归属（copyright holder）： BINARY Members

  • 版权年份： 2023

而不管之前的版权声明是什么。

注意：Update 还是 Remove + Add

update 命令的执行逻辑为将文件中第一个空行之前的内容识别为许可声明（如果有 shebang 则会保留），update 会根据指定的 flags 生成新的许可声明并进行替换。

如果您的文件第一个空行之前的内容包含了除了许可声明之外的内容，我建议您使用 remove + add 的形式来更新许可声明，这可以达到相同的效果，并且在 remove 中和模板文件 flag 一起使用可以达到更好的移除效果。

Flags

update 命令目前支持的 flags 如下表所示：

短标志长标志默认值介绍
-c--copyright<COPYRIGHT HOLDER>版权归属
-l--licenseapache许可证类型
-m--mutefalse (不指定)静默模式
-s--skip[]跳过的文件路径
-t--tmpl""模板文件路径
-y--yeartime.Now().Year() (当前年份)版权年份
-h--help无帮助

注意：如果您指定了模板，则 NWA 不会根据文件类型来更新对应的许可声明，而是更新路径下所有文件第一个空行前的内容为模板文件中指定的内容。

更多的使用示例请您参考 nwa-examples。

Check - 检查文件的许可声明

使用

nwa check [flags] path...

通过在 nwa 后面指定 check 命令来执行检查许可声明的操作，[flags] 表示可以添加 0 个或多个可选的 flag，path... 表示您可以指定一个或多个要检查许可声明的文件的路径。

使用示例

nwa check --tmpl tmpl.txt ./client

以上示例的命令表示 检查 相对路径为 ./client 文件夹下的所有文件许可声明是否与 tmpl.txt 模板文件中指定的内容相符。

检查完毕后，NWA 会以输出日志的形式来告知您检查的结果，一个样例输出如下：

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

check 命令目前支持的 flags 如下表所示：

短标志长标志默认值介绍
-c--copyright<COPYRIGHT HOLDER>版权归属
-l--licenseapache许可证类型
-m--mutefalse (不指定)静默模式
-s--skip[]跳过的文件路径
-t--tmpl""模板文件路径
-y--yeartime.Now().Year() (当前年份)版权年份
-h--help无帮助

注意：在使用 check 命令时不要与 -m flag 一起使用，因为这会让 NWA 无法输出检查的结果。

更多的使用示例请您参考 nwa-examples。

Config - 以配置文件的方式编辑文件的许可声明

使用

nwa config [flags] path

通过在 nwa 后面指定 config 命令来执行以配置文件的方式编辑文件的许可声明的操作，[flags] 表示可以添加 0 个或多个可选的 flag，path 表示您 必须指定 配置文件所在的路径。

使用示例

nwa config config.yaml

以上的示例命令表示读取 config.yaml 配置文件并根据其内容来编辑指定文件的许可声明，配置文件的结构将在下面提供。

Flags

由于所有的配置都位于配置文件，所以只有一个帮助 flag。

短标志长标志默认值介绍
-h--help无帮助

配置文件

一个完整的配置文件示例如下所示：

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

如果您不指定一些配置文件字段，NWA 将会使用默认值，比如如果您不指定许可证类型，则会默认使用 Apache 2.0 协议。

注意：如果您设置了 tmpl 字段，那么 holder，year 和 license 字段将被 NWA 忽略。

更多的使用示例请您参考 nwa-examples。

小结

以上内容就是对 NWA —— 一款更强大的许可声明管理工具 的介绍。

如果您觉得这个工具有帮助，请给我们的项目点个 Star 吧！

如果哪里写错了或者有问题欢迎评论或者私聊指出ww

参考列表

转载自:https://juejin.cn/post/7272025820967976996
评论
请登录