{"id":16312712,"url":"https://github.com/stepchowfun/tagref","last_synced_at":"2026-04-13T07:16:51.114Z","repository":{"id":32459435,"uuid":"134391783","full_name":"stepchowfun/tagref","owner":"stepchowfun","description":"Tagref helps you manage cross-references in your code.","archived":false,"fork":false,"pushed_at":"2025-09-11T06:21:18.000Z","size":371,"stargazers_count":212,"open_issues_count":2,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-06T18:05:08.100Z","etag":null,"topics":["continuous-integration","cross-reference","cross-references","cross-referencing","linter"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stepchowfun.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":"FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"stepchowfun"}},"created_at":"2018-05-22T09:26:42.000Z","updated_at":"2025-10-04T16:52:26.000Z","dependencies_parsed_at":"2023-11-22T14:47:48.596Z","dependency_job_id":"4580d4ca-bef6-400f-b3c4-9a517466d9c9","html_url":"https://github.com/stepchowfun/tagref","commit_stats":{"total_commits":240,"total_committers":7,"mean_commits":"34.285714285714285","dds":0.09166666666666667,"last_synced_commit":"98bcb684ef9016dcd3f3c627861ee61755b5137a"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/stepchowfun/tagref","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepchowfun%2Ftagref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepchowfun%2Ftagref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepchowfun%2Ftagref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepchowfun%2Ftagref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stepchowfun","download_url":"https://codeload.github.com/stepchowfun/tagref/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stepchowfun%2Ftagref/sbom","scorecard":{"id":851209,"data":{"date":"2025-08-11","repo":{"name":"github.com/stepchowfun/tagref","commit":"d06b705b579d716dc93fcd2d6cfe70f6e45d0f9f"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.5,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/15 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":5,"reason":"6 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 5","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: jobLevel 'contents' permission set to 'write': .github/workflows/ci.yml:190","Warn: no topLevel permission defined: .github/workflows/ci.yml:1"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:121: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:146: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:151: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:160: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:174: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:192: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:193: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:252: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:75: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:107: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:112: update your workflow using https://app.stepsecurity.io/secureworkflow/stepchowfun/tagref/ci.yml/main?enable=pin","Info:   0 out of  15 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.10.0 not signed: https://api.github.com/repos/stepchowfun/tagref/releases/146524657","Warn: release artifact v1.9.1 not signed: https://api.github.com/repos/stepchowfun/tagref/releases/143097110","Warn: release artifact v1.9.0 not signed: https://api.github.com/repos/stepchowfun/tagref/releases/142952594","Warn: release artifact v1.8.5 not signed: https://api.github.com/repos/stepchowfun/tagref/releases/142415200","Warn: release artifact v1.8.4 not signed: https://api.github.com/repos/stepchowfun/tagref/releases/109006408","Warn: release artifact v1.10.0 does not have provenance: https://api.github.com/repos/stepchowfun/tagref/releases/146524657","Warn: release artifact v1.9.1 does not have provenance: https://api.github.com/repos/stepchowfun/tagref/releases/143097110","Warn: release artifact v1.9.0 does not have provenance: https://api.github.com/repos/stepchowfun/tagref/releases/142952594","Warn: release artifact v1.8.5 does not have provenance: https://api.github.com/repos/stepchowfun/tagref/releases/142415200","Warn: release artifact v1.8.4 does not have provenance: https://api.github.com/repos/stepchowfun/tagref/releases/109006408"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":3,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Info: 'branch protection settings apply to administrators' is required to merge on branch 'main'","Warn: could not determine whether codeowners review is allowed","Info: 'up-to-date branches' is required to merge on branch 'main'","Info: status check found to merge onto on branch 'main'","Warn: PRs are not required to make changes on branch 'main'; or we don't have data to detect it.If you think it might be the latter, make sure to run Scorecard with a PAT or use Repo Rules (that are always public) instead of Branch Protection settings"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":6,"reason":"4 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: RUSTSEC-2021-0139","Warn: Project is vulnerable to: RUSTSEC-2021-0145 / GHSA-g98v-hv3f-hcfr","Warn: Project is vulnerable to: RUSTSEC-2024-0375","Warn: Project is vulnerable to: RUSTSEC-2020-0163"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-23T22:36:37.084Z","repository_id":32459435,"created_at":"2025-08-23T22:36:37.084Z","updated_at":"2025-08-23T22:36:37.084Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278655146,"owners_count":26022968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["continuous-integration","cross-reference","cross-references","cross-referencing","linter"],"created_at":"2024-10-10T21:48:54.642Z","updated_at":"2026-04-13T07:16:51.102Z","avatar_url":"https://github.com/stepchowfun.png","language":"Rust","funding_links":["https://github.com/sponsors/stepchowfun"],"categories":[],"sub_categories":[],"readme":"# Tagref\n\n[![Build status](https://github.com/stepchowfun/tagref/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/stepchowfun/tagref/actions?query=branch%3Amain)\n\n![Welcome to Tagref.](https://raw.githubusercontent.com/stepchowfun/tagref/main/tagref.svg?sanitize=true)\n\n*Tagref* helps you manage cross-references in your code. You can use it to help keep things in sync, document assumptions, maintain invariants, etc. [Airbnb](https://www.airbnb.com/), [Notion](https://www.notion.so/), and [Watershed](https://watershed.com/) use it to level up their code health. You can use it too!\n\nTagref works with any programming language, and it respects your `.gitignore` file as well as other common filter files. It's recommended to set up Tagref as an automated continuous integration (CI) check. Tagref is fast and almost certainly won't be the bottleneck in your CI.\n\n## What is it?\n\nTagref allows you to annotate your code with *tags* (in comments) which can be *referenced* from other parts of the codebase.\n\nHere's an example in Python:\n\n```python\n# [tag:polynomial_nonzero] This function never returns zero.\ndef polynomial(x):\n    return x ** 2 + 1\n\ndef inverse_polynomial(x):\n    return 1 / polynomial(x) # This is safe due to [ref:polynomial_nonzero].\n```\n\nTo help you manage these tags and references, Tagref checks the following:\n\n1. References actually point to tags. A tag cannot be deleted or renamed without updating the references that point to it.\n2. Tags are unique. There is never any ambiguity about which tag is being referenced.\n\nIn the example above, Tagref doesn't guarantee that `polynomial` returns a nonzero number. It isn't magic! It only ensures that the `polynomial_nonzero` tag exists unambiguously. The programmer is still responsible for keeping the comments in sync with the code.\n\nIn addition to references to tags, Tagref also supports *file references* and *directory references*. A file reference guarantees that the given file exists. For example:\n\n```python\n# If you bump the version, be sure to update [file:CHANGELOG.md].\n```\n\nA directory reference guarantees that the given directory exists. For example:\n\n```python\n# This script will format the files in [dir:src].\n```\n\nBy default, file and directory paths are relative to the working directory, which is typically the root of the project or repository. However, paths that start with a `.` or `..` component (e.g., `[file:./CHANGELOG.md]`) are considered relative to the directory containing the file where the reference originates.\n\n## Tag names\n\nThe name of a tag may consist of any UTF-8 text except the right square bracket `]`. Internal whitespace (as in `[tag:foo bar]`) is allowed, and surrounding whitespace (as in `[tag: baz ]`) is ignored. Tag names are case-sensitive, so `[tag:qux]` and `[tag:Qux]` are different tags.\n\nYou can use any naming convention you like. The Tagref authors prefer to use lowercase words separated by underscores `_`, like `[tag:important_note]`.\n\n## Usage\n\nThe easiest way to use Tagref is to run the `tagref` command with no arguments. It will recursively scan the working directory and check all the tags and references. Here are the supported command-line options:\n\n```\nUsage: tagref [OPTIONS] [COMMAND]\n\nCommands:\n  check        Check all the tags and references (default)\n  list-tags    List all the tags\n  list-refs    List all the tag references\n  list-files   List all the file references\n  list-dirs    List all the directory references\n  list-unused  List the unreferenced tags\n  help         Print this message or the help of the given subcommand(s)\n\nOptions:\n  -v, --version                  Print version\n  -p, --path \u003cPATH\u003e              Add a directory to scan [default: .]\n  -t, --tag-sigil \u003cTAG_SIGIL\u003e    Set the sigil used for tags [default: tag]\n  -r, --ref-sigil \u003cREF_SIGIL\u003e    Set the sigil used for tag references [default: ref]\n  -f, --file-sigil \u003cFILE_SIGIL\u003e  Set the sigil used for file references [default: file]\n  -d, --dir-sigil \u003cDIR_SIGIL\u003e    Set the sigil used for directory references [default: dir]\n  -h, --help                     Print help\n```\n\n## Installation instructions\n\n### Installation on macOS or Linux (AArch64 or x86-64)\n\nIf you're running macOS or Linux (AArch64 or x86-64), you can install Tagref with this command:\n\n```sh\ncurl https://raw.githubusercontent.com/stepchowfun/tagref/main/install.sh -LSfs | sh\n```\n\nThe same command can be used again to update to the latest version.\n\nThe installation script supports the following optional environment variables:\n\n- `VERSION=x.y.z` (defaults to the latest version)\n- `PREFIX=/path/to/install` (defaults to `/usr/local/bin`)\n\nFor example, the following will install Tagref into the working directory:\n\n```sh\ncurl https://raw.githubusercontent.com/stepchowfun/tagref/main/install.sh -LSfs | PREFIX=. sh\n```\n\nIf you prefer not to use this installation method, you can download the binary from the [releases page](https://github.com/stepchowfun/tagref/releases), make it executable (e.g., with `chmod`), and place it in some directory in your [`PATH`](https://en.wikipedia.org/wiki/PATH_\\(variable\\)) (e.g., `/usr/local/bin`).\n\n### Installation on Windows (AArch64 or x86-64)\n\nIf you're running Windows (AArch64 or x86-64), download the latest binary from the [releases page](https://github.com/stepchowfun/tagref/releases) and rename it to `tagref` (or `tagref.exe` if you have file extensions visible). Create a directory called `Tagref` in your `%PROGRAMFILES%` directory (e.g., `C:\\Program Files\\Tagref`), and place the renamed binary in there. Then, in the \"Advanced\" tab of the \"System Properties\" section of Control Panel, click on \"Environment Variables...\" and add the full path to the new `Tagref` directory to the `PATH` variable under \"System variables\". Note that the `Program Files` directory might have a different name if Windows is configured for a language other than English.\n\nTo update an existing installation, simply replace the existing binary.\n\n### Installation with Homebrew\n\nIf you have [Homebrew](https://brew.sh/), you can install Tagref as follows:\n\n```sh\nbrew install tagref\n```\n\nYou can update an existing installation with `brew upgrade tagref`.\n\n### Installation with Cargo\n\nIf you have [Cargo](https://doc.rust-lang.org/cargo/), you can install Tagref as follows:\n\n```sh\ncargo install tagref\n```\n\nYou can run that command with `--force` to update an existing installation.\n\n### Installation with pre-commit\n\nIf you use [pre-commit](https://pre-commit.com/), you can install Tagref by adding it to your `.pre-commit-config.yaml` as follows:\n\n```yaml\nrepos:\n- repo: https://github.com/stepchowfun/tagref\n  rev: v1.12.1\n  hooks:\n  - id: tagref\n```\n\nIf you happen to have Rust installed, make sure it's up-to-date since pre-commit will use it to install Tagref. If you don't already have Rust, pre-commit will install it for you.\n\n## Editor integrations\n\n- [tagref.el](https://github.com/vedang/tagref.el): An Emacs minor mode with tag/reference completion, xref-based navigation, and validation support.\n\n## Acknowledgements\n\nThe idea for Tagref was inspired by the GHC *notes* system described in [this article](http://www.aosabook.org/en/ghc.html) (§5.6).\n\n\u003c!-- \n  Reference the tags defined above so that `tagref list-unused --fail-if-any` succeeds.\n\n  - [ref:important_note]\n  - [ref:qux]\n  - [ref:Qux]\n  - [ref:foo bar]\n  - [ref:baz]\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstepchowfun%2Ftagref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstepchowfun%2Ftagref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstepchowfun%2Ftagref/lists"}