配置

许可需要使用配置文件。本节将解释配置文件的各个选项、它们的定义以及它们的工作原理。如果您正在寻找快速启动的方法，可以使用 licensure --generate-config 生成配置文件，这将为您提供一个带有文档注释的默认配置文件。

配置文件所在位置

配置文件是用 yaml 编写的，并从当前工作目录开始向上遍历目录树以查找名为 .licensure.yml 的文件。如果找不到，将使用位于 $XDG_CONFIG_HOME/licensure/config.yml（其中 $XDG_CONFIG_HOME 默认为 $HOME/.config）的全局配置文件。

这基本上意味着子目录可以有它们自己的许可配置，优先级顺序是当前工作目录最近的配置文件。

顶级配置选项

配置文件只有两个顶级选项： exclude 和 change_in_place。配置文件中的其他顶级键被称为配置部分，构成了许可配置的大部分。

change_in_place.

接受一个布尔值，指示在运行许可时是否要就地更改文件。如果设置为 false，则当使用此配置文件时，即使通过命令行提供了 --in-place，文件也永远不会就地更新。

示例配置

change_in_place: true

exclude

接受一个字符串列表，这些字符串将被编译为正则表达式，用于从许可中过滤文件。通过命令行标志传递的排除项将与配置文件中找到的任何排除项合并。

示例配置

# Regexes which if matched by a file path will always be excluded from
# getting a license header
excludes:
  - \.gitignore
  - .*lock
  - \.git/.*
  - \.licensure\.yml
  - README.*
  - LICENSE.*
  - .*\.(md|rst|txt)

配置部分

目前许可有两个配置部分： licenses 和 comments。它们配置了许可使用来生成许可头部的两个轴。

licenses

许可部分是一个许可配置对象的列表。许可配置对象定义了哪些许可证应应用于哪些文件、这些许可证的模板以及这些文件的版权所有者。一个许可配置对象具有以下形式

# Either a regex or the string "any" to determine to what files this
# license should apply. It is common for projects to have files
# under multiple licenses or with multiple copyright holders. This
# provides the ability to automatically license files correctly
# based on their file paths.
#
# If "any" is provided all files will match this license.
files: any

# The license identifier, a list of common identifiers can be
# found at: https://spdx.org/licenses/ but existence of the ident
# in this list it is not enforced unless auto_template is set to
# true.
ident: MIT

# A list of authors who hold copyright over these files
authors:
  # Provide either your full name or company name for copyright purposes
  - name: Your Name Here
    # Optionally provide email for copyright purposes
    # email: [email protected]

# The template that will be rendered to generate the header before
# comment characters are applied. Available variables are:
#  - [year]: substituted with the current year.
#  - [name of author]: Substituted with name of the author and email
#    if provided. If email is provided the output appears as Full
#    Name <[email protected]>. If multiple authors are provided the
#    list is concatenated together with commas.
template: |
  Copyright [year] [name of author]. All rights reserved. Use of
  this source code is governed by the [ident] license that can be
  found in the LICENSE file.

# If auto_template is true then the template configuration is ignored
# and the SPDX API will be queried with the ident value to
# automatically determine the license header template. auto_template
# works best with licenses that have a standardLicenseHeader field
# defined in their license info JSON, if it is not then we will use
# the full licenseText to generate the header which works fine for
# short licenses like MIT but can be quite lengthy for other licenses
# like BSD-4-Clause. The above default template is valid for most
# licenses and is recommended for MIT, and BSD licenses. Common
# licenses that work well with the auto_template feature are GPL
# variants, and the Apache 2.0 license.
#
# Important Note: this means the ident must be a valid SPDX identifier
# auto_template: true

一个常见的许可部分可能看起来像这样

licenses:
  - files: any
    authors:
      - name: Mathew Robinson
        email: [email protected]
        ident: MIT
    template: |
      Copyright [year] [name of author]. All rights reserved. Use of
      this source code is governed by the [ident] license that can be
      found in the LICENSE file.

年份范围

您也可以使用开始年份配置选项指定您的版权的年份范围。如果提供，许可将根据您的本地系统时间自动将年份范围放入您的版权中。一个具有 start_year 值为 2019 的示例将如下所示

Copyright 2019, 2024 ...

也可以指定 end_year，但如果省略，将自动根据您的本地系统时间自动更新为当前年份。

自动年份范围

如果您想要每个文件的年份范围或只是自动的年份范围，可以通过设置 use_dynamic_year_ranges: true 选项来选择。这将使用 git 提交信息来确定文件创建和最后更新的年份。然后根据 git 信息为该文件颁发一个特定的年份范围的许可证。

comments

注释部分是一个注释配置对象的列表。注释配置对象定义了如何注释具有特定扩展名的文件。它们还可以定义将生成的许可头部包装的列宽。一个注释配置对象具有以下字段： extensions（或 extension）、columns、commenter，

列配置

columns 键指定许可头部应包装的宽度。常见的值包括： 80、100、120。

示例

columns: 80

扩展配置

扩展名（或单个扩展名）字段定义了将注释应用于哪些文件扩展名。如果扩展名是字符串 "any"，则所有扩展名都将匹配此注释配置。

any 的示例使用

extension: any

显式扩展名的定义示例

extensions:
  - js
  - rs
  - go

注释者配置

注释者字段定义了要生成的注释类型。有两种类型的注释者：行和块。

行注释类型将在许可证头部每行的开头应用comment_char。然后，它将在头部末尾添加与trailing_lines相等的空行。

块注释类型将在许可证头部添加start_block_char作为第一个字符，并在许可证头部添加end_block_char作为最后一个字符。当提供per_line_char时，块开始和结束字符之间的头部每一行将以per_line_char进行行注释。

如果省略了 trailing_lines，则默认为 0。

行注释示例

这是行注释配置的一个例子。

commenter:
  type: line
  comment_char: "//"
  trailing_lines: 0

如果这个注释器给出了文本

A piece of text that
spans multiple lines

它将生成

// A piece of text that 
// spans multiple lines

注意：当 columns 有值时，文本可能会根据列宽进行重新换行。

块注释示例

这是块注释配置的一个例子。

commenter:
  type: block
  start_block_char: "/*\n"
  end_block_char: "*/"
  per_line_char: "*"
  trailing_lines: 0

如果这个注释器给出了文本

A piece of text that
spans multiple lines

它将生成

/*
* A piece of text that 
* spans multiple lines
*/

注意：当 columns 有值时，文本可能会根据列宽进行重新换行。

完整的配置示例

最佳的最小示例配置是 licensure 本身 的配置。

贡献

1. 分叉它！
2. 创建你的功能分支： git checkout -b my-new-feature
3. 提交你的更改： git commit -am 'Add some feature'
4. 推送到分支： git push origin my-new-feature
5. 🔥 提交一个拉取请求 :D 🔥

    Copyright (C) 2024 Mathew Robinson

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.