Lib.rs

› 命令行工具
#标签 #GitHub #仓库 #配置 #默认 #问题 #GitHub 标签

app labelmaker

在 GitHub 仓库中创建和强制执行标签集合

所有者 John T. Wodder II.

5 个版本 (重大更改)

0.5.0 2023 年 11 月 6 日
0.4.0 2023 年 10 月 30 日
0.3.0 2023 年 10 月 24 日
0.2.0 2023 年 10 月 22 日
0.1.0 2023 年 10 月 19 日

2283 在 命令行工具

MIT 许可证

175KB
4.5K SLoC

Project Status: Active – The project has reached a stable, usable state and is being actively developed. CI Status codecov.io Minimum Supported Rust Version MIT License

GitHub | crates.io | 问题 | 变更日志

labelmaker 是一个 Rust 程序，用于在 GitHub 仓库中批量创建 标签，包括更新和/或重命名现有标签以满足您的规格。只需在配置文件中描述您想要的标签，然后将 labelmaker 指向您的仓库。

安装

要安装 labelmaker，您首先需要安装 Rust 和 Cargo。然后，您可以通过运行以下命令来构建 labelmaker 的最新版本并将其安装到 ~/.cargo/bin：

cargo install labelmaker

用法

labelmaker [<global options>] <subcommand> ...

labelmaker 命令具有以下子命令，每个子命令的详细信息如下：

  • apply — 将一组标签规格应用于一个或多个 GitHub 仓库

  • fetch — 将仓库的标签作为配置文件导出

  • make — 创建或更新单个标签

每个子命令都接受一个或多个参数或选项，以指定要操作的 GitHub 仓库。仓库可以指定为 OWNER/NAME 的形式（或者，当 OWNER 是认证用户时，只需 NAME）或作为 GitHub 仓库 URL。如果没有提供仓库，则当前目录必须属于一个 Git 仓库，其 origin 远程指向一个 GitHub 仓库；labelmaker 将在此远程仓库上操作。

全局选项

  • -l <level>, --log-level <level> — 将日志级别设置为指定值。可能的值有 "OFF", "ERROR", "WARN", "INFO", "DEBUG" 和 "TRACE"（不区分大小写）。[默认值: INFO]

身份验证

labelmaker 运行需要 GitHub 访问令牌，并且具有适当的权限。通过 GH_TOKEN 或 GITHUB_TOKEN 环境变量指定令牌，或者使用 gh 命令存储。

注意，如果 gh 在系统密钥环中存储了令牌，则可能会提示您解锁密钥环。

labelmaker apply

labelmaker [<global options>] apply [<options>] <config-file> [<repository> ...]

labelmaker apply 接受配置文件（见下文“配置文件”）的路径和 GitHub 仓库列表作为参数。然后根据配置文件中的说明创建和/或更新每个仓库的标签。

对于每个仓库，在修改任何内容之前先计算所有更改，所以如果在配置文件的状态和/或当前仓库标签的状态出现错误，它将在对仓库进行任何更改之前被捕获。

选项

  • --dry-run — 不要更改 GitHub 中的任何内容，但会输出将要更改的日志消息。

  • -F FILE/--repo-file FILE — 对给定文件中列出的所有仓库进行操作。仓库必须每行一个。忽略前导和尾随空格。跳过空行和以 # 开头的行。

  • -P NAME/--profile NAME — 指定配置文件中要使用的配置文件。默认为配置文件中 defaults.profile 的值，或默认为 default。

labelmaker fetch

labelmaker [<global options>] fetch [<options>] [<repository>]

labelmaker fetch 获取给定 GitHub 仓库当前定义的标签，并将其作为 labelmaker 配置文件输出，以便于 labelmaker apply 使用。

生成的配置文件只列出标签名称、颜色和描述，没有默认值，除了文件全局的 color 设置包含其默认值作为参考。

选项

  • -o FILE/--outfile FILE — 将配置输出到指定的文件。默认情况下，输出写入标准输出，也可以通过提供 - 作为输出文件名称来选择。

    输出格式（JSON、JSON5、TOML 或 YAML）基于文件的扩展名确定。当输出到标准输出时，生成 JSON。

  • -P NAME/--profile NAME — 设置在生成的配置文件中将标签放置的配置文件名称。配置文件的默认配置文件也将设置为该值。[默认: default]

labelmaker make

labelmaker [<global options>] make [<options>] <label-name>

labelmaker make 在 GitHub 仓库中创建或更新指定名称的标签，等同于在该仓库上运行了 labelmaker apply 命令，并且配置文件中只包含一个标签条目。

选项

  • -c COLOR/--color COLOR — 指定标签的颜色。颜色使用与配置文件相同的格式指定。

    此选项可以指定多次，在这种情况下，创建标签时将随机选择给定的颜色之一，并且更新标签时不会更改标签颜色。

    默认颜色为从与配置文件和 apply 使用的相同内置列表中随机选择。

  • --create/--no-create — 如果标签不存在，是否创建标签 [默认：--create]

  • -TEXT，--description TEXT — 指定标签的描述。

  • --dry-run — 不要更改 GitHub 中的任何内容，但会输出将要更改的日志消息。

  • --enforce-case/--no-enforce-case — 如果现有标签的名称与命令行中给出的名称大小写不同，是否重命名标签 [默认：--enforce-case]

  • --on-rename-clash <ignore|warn|error> — 如果标签存在且存在一个或多个 --rename-from 标签，指定要执行的操作

    • ignore：不执行任何操作
    • warn (默认)：发出警告
    • error：失败并报错

  • --rename-from LABEL — 如果 LABEL 存在，将其重命名为 make 命令提供的标签名称。

    此选项可以指定多次。如果存在多个 --rename-from 标签，将发生错误。

  • -R REPO/--repository REPO — 指定要操作的 GitHub 仓库。

  • --update/--no-update — 如果标签的颜色和/或描述与命令行中给出的值不匹配，是否更新标签 [默认：--update]

配置文件

labelmaker 的配置文件可以编写为 JSON、JSON5、TOML 或 YAML 格式；文件类型根据文件扩展名自动确定。文件包含顶层映射，具有以下字段

  • defaults — 一个映射，将默认标签设置应用于此配置文件中的所有标签。除了 name 和 rename-from 之外，可以在标签上设置的任何字段都可以在此处设置。全局默认值可以通过 profiles.*.defaults 映射覆盖特定配置文件。

    • defaults 映射还可以包含一个 profile 字符串字段，指定 apply 使用默认配置文件时没有给出 --profile 选项的情况下的默认配置文件；默认配置文件是 default。

  • profiles — 从配置文件名到配置定义的映射。一个配置文件是一组标签定义，可以在调用apply时选择。每个配置文件由以下字段定义的映射组成：

    • defaults — 将应用于此配置文件中所有标签的默认标签设置映射。除了name和rename-from之外，可以设置标签上的任何字段。在此处设置的设置将覆盖顶级defaults映射中为该配置文件中的标签设置的设置。

    • labels — 标签规范列表；每个标签都是一个包含以下字段的映射：

      • name (必需) — 标签的名称。将删除前导和尾随空格；如果结果字符串为空，则是一个错误。

        • 请注意，GitHub对标签名称不区分大小写；因此，“foo”和“Foo”指的是相同的标签。如果您希望标签名称强制执行特定的字母大小写，请参阅下面的enforce-case选项。

        • 如果同一配置文件中的两个或多个标签在大小写折叠后具有相同的名称，则是一个错误。

      • color — 要用于标签的颜色。颜色可以指定为十六进制RGB字符串"#rrggbb"（带有或不带有前导#）或作为CSS颜色名称。或者，可以将color设置为颜色列表，在这种情况下，在创建标签时将随机选择其中一个颜色，并且在更新标签时不会更改标签颜色。空列表等效于["#000000"]。

        默认的color值是截至2023-09-24在GitHub Web UI中创建新标签时显示的默认颜色列表。

      • description — 要应用于标签的描述。如果未设置，则在创建标签时描述将为空，并且在更新标签时不会更改描述。

      • create（布尔值；默认：true）—— 如果为真，则标签不存在，并且没有在rename-from中指定的标签存在（见下文），则在GitHub中创建标签。

      • update（布尔值；默认：true）—— 如果为真，则标签存在（或正在将rename-from中指定的标签重命名为它），并且现有标签的颜色和/或描述与配置文件中给出的值不同，则更新不同的字段。

      • enforce-case（布尔值；默认：true）—— 如果为真，并且标签存在，但GitHub中标签的名称与name中比较时的名称在大小写敏感时不同，则更新标签以使用配置文件中指定的字母大小写。

      • rename-from—— 标签名称列表；如果name字段中给出的标签在该存储库中不存在，但rename-from中的标签之一存在，则现有标签将重命名为给定的name。如果rename-from中的多个标签存在，则将发生错误。

        • 如果name中给出的标签存在，并且rename-from中也有一个或多个标签存在，则默认会发出警告；请参阅下面的on-rename-clash选项。

        • 如果标签在rename-from中包含其自己的名称，则是一个错误。

        • 如果配置文件中指定的标签也出现在同一配置文件中另一个标签的rename-from列表中，则是一个错误。

        • 如果一个标签出现在同一配置文件中两个或更多标签的rename-from字段中，则是一个错误。

      • on-rename-clash — 指定如果标签存在且rename-from中列出的一个或多个标签也存在时应该做什么。可能的值有

        • "ignore" — 不做任何事情。
        • "warn" (默认) — 发出警告。
        • "error" — 以错误失败。

示例配置文件

以下TOML配置显示了截至2023-10-18的默认GitHub标签，以及默认的color设置值

[defaults]
color = [
    "0052cc",
    "006b75",
    "0e8a16",
    "1d76db",
    "5319e7",
    "b60205",
    "bfd4f2",
    "bfdadc",
    "c2e0c6",
    "c5def5",
    "d4c5f9",
    "d93f0b",
    "e99695",
    "f9d0c4",
    "fbca04",
    "fef2c0",
]

[[profiles.default.labels]]
name = "bug"
color = "d73a4a"
description = "Something isn't working"

[[profiles.default.labels]]
name = "documentation"
color = "0075ca"
description = "Improvements or additions to documentation"

[[profiles.default.labels]]
name = "duplicate"
color = "cfd3d7"
description = "This issue or pull request already exists"

[[profiles.default.labels]]
name = "enhancement"
color = "a2eeef"
description = "New feature or request"

[[profiles.default.labels]]
name = "good first issue"
color = "7057ff"
description = "Good for newcomers"

[[profiles.default.labels]]
name = "help wanted"
color = "008672"
description = "Extra attention is needed"

[[profiles.default.labels]]
name = "invalid"
color = "e4e669"
description = "This doesn't seem right"

[[profiles.default.labels]]
name = "question"
color = "d876e3"
description = "Further information is requested"

[[profiles.default.labels]]
name = "wontfix"
color = "ffffff"
description = "This will not be worked on"

相同的配置，以YAML格式表示

defaults:
  color:
    - "0052cc"
    - "006b75"
    - "0e8a16"
    - "1d76db"
    - "5319e7"
    - "b60205"
    - "bfd4f2"
    - "bfdadc"
    - "c2e0c6"
    - "c5def5"
    - "d4c5f9"
    - "d93f0b"
    - "e99695"
    - "f9d0c4"
    - "fbca04"
    - "fef2c0"

profiles:
  default:
    labels:
      - name: bug
        color: "d73a4a"
        description: Something isn't working

      - name: documentation
        color: "0075ca"
        description: Improvements or additions to documentation

      - name: duplicate
        color: "cfd3d7"
        description: This issue or pull request already exists

      - name: enhancement
        color: "a2eeef"
        description: New feature or request

      - name: good first issue
        color: "7057ff"
        description: Good for newcomers

      - name: help wanted
        color: "008672"
        description: Extra attention is needed

      - name: invalid
        color: "e4e669"
        description: This doesn't seem right

      - name: question
        color: "d876e3"
        description: Further information is requested

      - name: wontfix
        color: "ffffff"
        description: This will not be worked on

依赖项

~15–30MB
~501K SLoC