M0003 git-dependency-pins¶
Rule: Git dependencies are pinned the way the project's policy says: a branch by default.
| Code | M0003 (stable, never reused) |
| Id | git-dependency-pins |
| Category | dependencies |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
git dependencies follow a branch; Cargo.lock fixes the commit |
| small-workspace | warn |
git dependencies follow a branch; Cargo.lock fixes the commit |
| medium | deny |
git dependencies follow a branch; a pin hides a break until it is old |
| big | deny |
git dependencies follow a branch; a pin hides a break until it is old |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
policy |
one of "branch", "default-branch", "dev-branch", "tag", "release", "any" | "branch" |
how a git dependency on another project's repo is pinned |
own |
list of strings | [] |
git URL prefixes of the project's own repos (github.com/org, a host) |
own-policy |
one of "branch", "default-branch", "dev-branch", "tag", "release", "any" | "branch" |
how a git dependency on one of the project's own repos is pinned |
dev-branch |
string | "dev" |
the branch the dev-branch policy follows |
Why¶
How a git dependency is pinned follows the stage of the repos on both ends. Cargo.lock fixes the commit whatever Cargo.toml says, so a pin in Cargo.toml decides only how a dependency moves on: with cargo update -p NAME, or with an edit by hand. The project states its policy once, and the lint holds every git dependency to it.
| Policy | A git dependency names | Fits when |
|---|---|---|
branch (default) |
a branch or nothing; no rev or tag |
development is early: a break in the other repo shows at once, Cargo.lock holds the commit, no SHA is edited by hand |
default-branch |
nothing: no branch, rev or tag |
the other repo's default branch is the one to follow, and a branch name in Cargo.toml would only go stale |
dev-branch |
branch = "<dev-branch>", no rev or tag |
the other repo works on a dev branch and keeps main quiet for its outside users; often makes tags unnecessary |
tag |
a tag, no rev or branch |
the other repo has outside users and releases by tag; active work happens on a branch or behind a [patch] override kept out of git |
release |
nothing from git: a registry version | the other repo publishes to crates.io and the project takes its releases |
any |
anything | the lint should not check pins |
policy applies to other projects' repos and own-policy to the project's own, named by URL prefix in own (a host, or a host and an org). The two often differ: the project's own libraries move with it on a branch while outside crates come by tag or release. URLs compare without scheme, git@, .git and case, so git@github.com:acme/x.git is under github.com/acme.
Example¶
A product whose own libraries follow their default branch, and whose outside git dependencies come by tag:
[lints.git-dependency-pins]
level = "deny"
reason = "own libraries move with us; outside ones by release tag"
own = ["github.com/acme", "git.acme.dev"]
own-policy = "default-branch"
policy = "tag"
How to fix¶
Write the dependency the way the policy says: drop the rev, tag or branch it does not allow, add the one it asks for, or take a registry release. Then cargo update -p NAME moves Cargo.lock to it. When the stage of a repo changes, change the policy, not each dependency's exception.
Configure¶
[lints.git-dependency-pins]
level = "deny"
policy = "branch"
own = []
own-policy = "branch"
dev-branch = "dev"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(git-dependency-pins) <reason> (waivers); the code works there too, as in [lints.M0003].