用法#

这个概述记录了如何使用此工具的一些基本用法。强烈建议您先阅读概述，您甚至可能不需要阅读本章。本章涵盖了可能不会立即生效的详细信息使用工具时明显可见。本章不包括一切，假设用户得到了足够的帮助重新使用 --帮助和重新使用 <子命令> --帮助.

实施细节#

本节介绍了适用于整个工具的实现细节。

在文件中搜索版权和许可标签时，该工具会不严格地将其自身限制为规范。它搜索文件的前4 KB。这确保了该工具可以解析任何类型的纯文本文件，即使注释样式无法识别。

如果发现文件具有无法解析的标记，则根本不会分析该文件。这是臭虫.

运行该工具时，如果工作目录位于VCS存储库中。否则，它会处理工作目录作为项目的根目录。您可以覆盖项目的根使用--根可选参数。

Git子模块自动忽略，除非--包含子模块是作为可选参数传递。

如果出现以下情况，则会自动忽略Meson子项目介观建造存在于项目根目录。--包括子项目覆盖此行为。

自动忽略零大小的符号链接和文件。

注释#

警告

你应该谨慎使用注释在自动化过程中。While期间没有什么可以阻止您在发布脚本中使用它，您应该确保它添加的信息实际上反映了现实。这是最好手动验证。

基本用法是重新使用注释 --copyright=“简 Doe（多伊）” --许可证=麻省理工学院我的文件.py。这将向文件中添加以下标头（假设当前年份为2019年）：

#SPDX文件版权文本：2019 Jane Doe
#
#SPDX-License-Identifier:麻省理工学院

您可以使用尽可能多的--版权和--许可证参数，只要至少有一个这样的论点。

REUSE标头位于文件的最顶部。如果不同的重复使用标头已经存在-位于顶部或其他位置-它的标记被复制，并且收割台就地更换。

有了这个论点--版权风格可以更改默认值SPDX文件版权文本以下样式之一：

spdx:spdx-File版权文本：<年份><声明>spdx-c:spdx-File版权文本：（c）<年份><声明>spdx符号：spdx文件版权文本：©＜年份＞＜声明＞string：版权所有<year><statement>string-c：版权所有（c）<年份><声明>字符串符号：版权所有©<年份><声明>符号：©<年份><声明>

Shebangs总是保存在文件的顶部。如果你也想保留现有标头，使用参数--无替换.

合并报表#

当该工具解析版权标头时，重新使用可以配置为基于语句元素自动合并版权行。这有效地将一年内的多行转换为一行范围。

从下面的标题开始，

#SPDX文件版权文本：2016 Jane Doe
#SPDX文件版权文本：2018 John Doe
#
#SPDX-License-Identifier:GPL-2.0

标准工具选项将产生以下结果

$重新使用 注释 --年 2018 --许可证 GPL-2.0标准 --版权=“无名氏” 文件.py

#SPDX文件版权文本：2016 Jane Doe
#SPDX文件版权文本：2018 John Doe
#SPDX文件版权文本：2018 Jane Doe
#
#SPDX-License-Identifier:GPL-2.0

使用–合并版权选项将改为生成以下内容

#SPDX文件版权文本：2016-2018 Jane Doe
#SPDX文件版权文本：2018 John Doe
#
#SPDX-License-Identifier:GPL-2.0

注释样式#

该工具通常会尝试从文件中自动检测要使用的注释样式文件的扩展名，并使用该注释样式。如果工具无法检测注释样式，或者如果它检测到错误的样式，您可以覆盖该样式使用--风格。样式列表可在中找到reuse.comment模块.

如果您的注释样式不受支持或文件扩展名不正确检测到了，请打开问题.

通常，工具在可用时使用单行注释样式（例如。，//使用而不是/* */对于C注释样式）。如果没有单行注释样式可用，则使用多行样式。你可以强制发表某个评论样式使用–单线或–多线.

模板#

当该工具向文件添加标题时，通常首先列出所有版权语句按字母顺序添加一个空行，然后列出所有SPDX按字母顺序排列许可证表达式。这就是标题所包含的全部内容。它是可以更改此行为，并使用包含额外文本。这是通过Jinja2模板完成的。

默认模板为：

{% 对于 版权_行 在里面 版权_行 %}
{{ 版权_行 }}
{% 外循环 %}
{% 对于 出资人行 在里面 出资人行 %}
SPDX文件贡献者：{{ 出资人行 }}
{% 外循环 %}

{% 对于 表达 在里面 spdx表达式（_E） %}
SPDX许可证标识符：{{ 表达 }}
{% 外循环 %}

根据检测到的或指定的注释样式。

您可以创建自己的Jinja2模板并将其放置在.重用/模板/。如果创建模板我的模板.jinja2，你可以与一起使用重新使用注释 --copyright=“简 “Doe” --template=mytemplate 食品.py.

在模板内部，您可以访问以下变量：

版权_行-版权声明列表（字符串）。
出资人行-贡献者列表（字符串）。
spdx表达式（_E）-SPDX许可证表达式列表（字符串）。

未来将添加更多变量。

在某些情况下，您可能需要自定义注释格式。在这些情况下，您可以将标题预先格式化为注释。进行此操作时，为模板添加后缀具有.评论.jinja2.

带有手动注释的自定义模板示例如下：

/*
{% 对于 版权_行 在里面 版权_行 %}
*{{ 版权_行 }}
{% 外循环 %}
{% 如果 版权_行 和 spdx表达式（_E） %}
*
{% 结尾 %}
{% 对于 表达 在里面 spdx_表达式 %}
*SPDX许可证标识符：{{ 表达 }}
{% 外循环 %}
{% 如果 “GPL-3.0级” 在里面 spdx表达式（_E） %}
*
*这个程序是自由软件：你可以重新发布和/或在下面修改它
*自由软件发布的GNU通用公共许可证的条款
*基金会，许可证版本3或（根据您的选择）任何更高版本
*版本。
*
*这个程序的发布是希望它会有用，但没有
*任何保证；甚至没有适销性或适用性的暗示保证
*出于特定目的。有关更多详细信息，请参阅GNU通用公共许可证。
*
*您应该已经收到GNU通用公共许可证的副本以及
*这个程序。如果没有，请参阅<https://www.gnu.org/licenses网站/>.
{% 结尾 %}
*/

皮棉#

皮棉是工具的主要组件。总之，它会验证项目符合再利用规范。其主要目标是查找所有不在标题中包含版权和许可信息，但它还检查几乎没有其他事情。

的STDOUT输出重新使用皮棉是有效的降价。偶尔会有一些伐木将打印到STDERR，这是无效的降价。

您可以使用–安静选项。这可能很有用如果您只对退出代码感兴趣。

这是的一些输出示例重新使用皮棉:

#不良许可证“bad-license”位于：*许可证/bad-license.txt#未使用的许可证未使用以下许可证：*非法许可证#缺少版权和许可信息以下文件没有版权和许可信息：*无信息.txt#总结*错误的许可证：错误的许可*弃用的许可证：*无文件扩展名的许可证：*缺少许可证：*未使用的许可证：无效许可证*使用的许可证：Apache-2.0、CC-BY-SA-4.0、CC0-1.0、GPL-3.0-or-later*读取错误：0*包含版权信息的文件：57/58*包含许可证信息的文件：57/58遗憾的是，您的项目不符合REUSE规范的3.0版本：-(

标准#

短绒检查的标准如下：

错误的许可证#

在中找到的许可证许可证/在SPDX许可证中找不到的列出或不以开头许可证参考-是错误的许可证。

弃用的许可证#

如果许可证的SPDX许可证标识符已被SPDX弃用，许可证会显示在这里。

没有文件扩展名的许可证#

这些许可证的文件名是有效的SPDX许可证标识符，但是没有文件扩展名的。

缺少许可证#

如果在注释标题中引用了许可证，但在中找不到该许可证这个许可证/目录，则该许可证丢失。

未使用的许可证#

相反，如果在许可证/目录，但不是在任何注释标题中引用，则该许可证未被使用。

读取错误#

技术上不是标准，但操作人员无法读取的文件系统存在读取错误，需要修复。

包含版权和许可证信息的文件#

每个文件都需要有与其相关的版权和许可信息。《再利用规范》详细介绍了几种实现方法方法如下：

在文件头中放置标记。
将标记放置在.许可证文件旁边的文件。
将信息放入DEP5文件中。

如果发现文件没有版权和/或许可信息与之关联，则项目不符合。

忽略文件的部分#

您可以轻松忽略文件中始终会导致以下问题的部分重新使用皮棉。假设您有以下bash脚本：

#!/usr/bin/env-bash
#SPDX文件版权文本：2021 John Doe
#
#SPDX-License-Identifier:CC0-1.0

回声 “SPDX文件版权文本：$(日期 +“%Y”)无名氏“ > 文件.txt回声 “SPDX-License-Identifier:MIT” > 文件.txt出口 0

尽管文件具有标头中的正确许可信息：

$重新使用皮棉重复使用_util-错误-无法解析'MIT“>file.txt'reuse.project-ERROR-“foobar.sh”包含无法解析的SPDX表达式，跳过该文件#缺少版权和许可信息以下文件没有版权和许可信息：*foobar.sh[...]

为了避免出现此错误消息，您可以简单地修改文件，如下所示：

#!/usr/bin/env-bash
#SPDX文件版权文本：2021 John Doe
#
#SPDX-License-Identifier:CC0-1.0

#重复-忽略启动
回声 “SPDX文件版权文本：$(日期 +“%Y”)无名氏“ > 文件.txt回声 “SPDX-License-Identifier:MIT” > 文件.txt#重复-忽略结束

出口 0

现在，重复使用棉绒将不再报告此文件的任何问题。