Tagref

Tagref帮助您管理代码中的交叉引用。您可以使用它来帮助保持同步、记录假设、维护不变性等。Airbnb、Notion和Watershed都在使用它。您也可以使用它！

Tagref与任何编程语言兼容，并且它尊重您的.gitignore文件以及其他常见过滤器文件。建议将Tagref设置为自动化持续集成（CI）检查。Tagref运行速度快，几乎不会成为CI的瓶颈。

这是什么？

Tagref允许您使用标签（在注释中）注释您的代码，这些标签可以从代码库的其他部分进行引用。

以下是一个Python示例。下面的polynomial函数返回一个非零数字

def polynomial(x):
    return x ** 2 + 1

假设您想在某个地方使用该函数（可能在不同的文件中），并且您的代码依赖于该函数永远不会返回零的事实

def inverse_polynomial(x):
    return 1 / polynomial(x)

这会让人感到有些不舒服。如果有人更改了polynomial的定义，您的代码可能会引发ZeroDivisionError！因此，您在定义polynomial的地方添加一个标签

# [tag:polynomial_nonzero] This function never returns zero.
def polynomial(x):
    return x ** 2 + 1

现在您可以在代码中引用该标签

def inverse_polynomial(x):
    return 1 / polynomial(x) # This is safe due to [ref:polynomial_nonzero].

为了帮助您管理这些标签和引用，Tagref检查以下内容

1. 引用实际上指向标签。如果删除或重命名标签，则必须更新指向它的引用。
2. 标签是唯一的。永远不会对引用哪个标签有歧义。

在上面的示例中，Tagref并不能保证polynomial返回一个非零数字。它不是魔法！它只确保polynomial_nonzero标签明确存在。程序员仍需负责确保注释与代码保持同步。

除了对标签的引用之外，Tagref还支持文件引用和目录引用。文件引用保证给定文件存在。例如

# If you bump the version, be sure to update [file:CHANGELOG.md].

目录引用保证给定目录存在。例如

# This script will format the files in [dir:src].

标签名称

标签的名称可以由任何UTF-8文本组成，但不能包含空格和右方括号]。内部空格（如[tag:foo bar]）是允许的，并且周围的空格（如[tag: baz ]）将被忽略。有效的标签示例还包括：[tag:foo_bar]和[tag:ほげ〜ふが]。标签名称区分大小写，因此[tag:foo]和[tag:Foo]是不同的标签。

您可以使用任何喜欢的命名约定。Tagref的作者更喜欢使用下划线分隔的小写单词，如[tag:important_note]。

用法

使用Tagref最简单的方法是运行不带参数的tagref命令。它将递归扫描工作目录并检查所有标签和引用。以下是一些支持的命令行选项

USAGE:
    tagref [SUBCOMMAND]

OPTIONS:
    -d, --dir-sigil <DIR_SIGIL>
            Sets the sigil used for directory references [default: dir]

    -f, --file-sigil <FILE_SIGIL>
            Sets the sigil used for file references [default: file]

    -h, --help
            Prints help information

    -p, --path <PATH>...
            Adds the path of a directory to scan [default: .]

    -r, --ref-sigil <REF_SIGIL>
            Sets the sigil used for tag references [default: ref]

    -t, --tag-sigil <TAG_SIGIL>
            Sets the sigil used for tags [default: tag]

    -v, --version
            Prints version information


SUBCOMMANDS:
    check
            Checks all the tags and references (default)

    help
            Prints this message or the help of the given subcommand(s)

    list-dirs
            Lists all the directory references

    list-files
            Lists all the file references

    list-refs
            Lists all the tag references

    list-tags
            Lists all the tags

    list-unused
            Lists the unreferenced tags

安装说明

在macOS或Linux（AArch64或x86-64）上安装

如果您正在运行macOS或Linux（AArch64或x86-64），可以使用以下命令安装Tagref

curl https://raw.githubusercontent.com/stepchowfun/tagref/main/install.sh -LSfs | sh

可以使用相同的命令再次运行以更新到最新版本。

安装脚本支持以下可选环境变量

• VERSION=x.y.z（默认为最新版本）
• PREFIX=/path/to/install（默认为/usr/local/bin）

例如，以下操作将安装Tagref到工作目录

curl https://raw.githubusercontent.com/stepchowfun/tagref/main/install.sh -LSfs | PREFIX=. sh

如果您不希望使用此安装方法，可以从发布页面下载二进制文件，使其可执行（例如，使用chmod），并将其放置在您的PATH目录中的某个目录（例如，/usr/local/bin）。

在Windows（AArch64或x86-64）上安装

如果您正在运行Windows（AArch64或x86-64），请从发布页面下载最新二进制文件，并将其重命名为tagref（如果您已显示文件扩展名，则为tagref.exe）。在您的%PROGRAMFILES%目录中创建一个名为Tagref的目录（例如，C:\Program Files\Tagref），并将重命名的二进制文件放在其中。然后，在控制面板“系统属性”部分的“高级”选项卡中，单击“环境变量...”，并将新Tagref目录的完整路径添加到“系统变量”下的PATH变量。请注意，如果Windows配置为非英语语言，则Program Files目录可能有不同的名称。

要更新现有安装，只需替换现有二进制文件即可。

使用Homebrew安装

如果您有Homebrew，可以按照以下方式安装Tagref

brew install tagref

您可以使用brew upgrade tagref更新现有安装。

使用Cargo安装

如果您有 Cargo，您可以按照以下步骤安装 Tagref

cargo install tagref

您可以使用 --force 参数运行该命令来更新现有安装。

使用 pre-commit 进行安装

如果您使用 pre-commit，可以通过将其添加到您的 .pre-commit-config.yaml 中来安装 Tagref，如下所示

repos:
- repo: https://github.com/stepchowfun/tagref
  rev: v1.9.1
  hooks:
  - id: tagref

如果您已经安装了 Rust，请确保它是最新版本，因为 pre-commit 将使用它来安装 Tagref。如果您还没有安装 Rust，pre-commit 将为您安装它。

致谢

Tagref 的想法受到了 GHC 注释约定 的启发。有关 GHC 开发人员如何管理他们的代码库的更多信息，请参阅 这篇文章。