skip to content

A Rust crate's Cargo.toml has a git dependency pinned by `rev` and a path dependency on a sibling crate; how does Cargo source each, and what must change before `cargo publish`?

level: seniorimportance: should knowfreq 34%

answer

  1. a lockfile entry for the commit
  2. path is relative to this manifest
  3. version means a registry exists
  4. packaging strips git and path

basics

~20 s

Cargo fetches the git repository at the given rev and builds the path crate from that folder. Publishing needs a version on every non-dev dependency: git and path keys are stripped and registry versions used, so each must exist in the registry.

solid answer

~50 s

For a **git** dependency Cargo clones the repository, finds the named crate's `Cargo.toml` anywhere in it, builds the commit chosen by exactly one of `branch`, `tag` or `rev` (the default branch's latest commit if none), and records that commit in `Cargo.lock`. A **path** dependency is built straight from the folder given relative to the manifest, which must contain the crate's own `Cargo.toml`. Neither can be published as is: `cargo package` and `cargo publish` fail with "all dependencies must have a version requirement specified when packaging". Adding `version = "0.4"` beside `path` or `git` keeps local builds on the local source, checking its version against the requirement, while the packaged manifest drops `path`/`git` and depends on the registry release. So the sibling crate must be published first, and a git fix must reach a registry release, because crates.io accepts only crates.io dependencies, dev-dependencies aside.

code

toml · 9 lines
toml
[package]
name = "ledger-api"
version = "0.1.0"
edition = "2024"
license = "MIT"
description = "Ledger HTTP API"

[dependencies]
ledger-model = { path = "crates/ledger-model" }

go deeper

for a junior

Recall that git and path dependencies build from a repository or a folder, and that a published crate needs registry versions for them.

for a middle

Explain branch, tag and rev, why the commit is locked in Cargo.lock, and how path is resolved relative to the manifest.

for a senior

Explain what version beside git or path does in each setting, why the sibling must be published first, and why a git fix is lost when the crate is published.

for a principal

Decide when an internal crate earns a registry release versus staying a path dependency, given that every publish order and version bump becomes release work.

## Three sources for one dependency line A dependency in `Cargo.toml` can come from a **registry** (crates.io by default, or another registry named with `registry = "..."`), from a **git** repository, or from a **path** on disk. A crate in a service repository often uses all three. Two of them are local conveniences that a published crate cannot keep. ## Git dependencies `ledger-proto = { git = "https://git.example.com/payments/ledger-proto.git", rev = "4c59b707" }` tells Cargo to fetch that repository. The details that come up in review: - **Which commit.** With only `git`, Cargo uses the latest commit on the default branch. `branch`, `tag` or `rev` narrows it, and exactly one is allowed; combining `branch` and `rev` is a manifest error ("Only one of `branch`, `tag` or `rev` is allowed."). `rev` takes anything that is not a branch or tag: a commit hash, or a named reference the host exposes, such as `refs/pull/493/head`. - **Locking.** Cargo records the resolved commit in `Cargo.lock` when the dependency is added and looks for newer commits only when you run `cargo update`. A `rev` that is a commit hash keeps the same commit even then; a `branch` dependency moves on `cargo update`. - **Finding the crate.** Cargo searches the whole repository for a `Cargo.toml` naming the crate, so several crates in one repository can share the root URL. - **Mistakes Cargo flags.** A commit after `#` in the URL is ignored with a warning that suggests `rev` instead, and `git` together with `path` is rejected as ambiguous. Submodules are fetched recursively. ## Path dependencies `ledger-model = { path = "crates/ledger-model" }` points at a folder **relative to the `Cargo.toml` it is written in**. Unlike `git`, Cargo does not search below that folder: the path must name the exact directory holding the dependency's own `Cargo.toml`. The crate is compiled from source like a local package, and edits to it show up on the next build. ## The version key: local source, registry when published The Cargo book says the `version` key "always implies that the package is available in a registry, regardless of the presence of git or path keys". Adding it gives the line two meanings: 1. **Locally**, Cargo still uses the git or path source, and checks the source's own version against the requirement. A sibling at 0.3.1 with `version = "0.2"` fails with "failed to select a version for the requirement". 2. **When packaged**, Cargo rewrites the manifest inside the `.crate`: the `git` or `path` key is removed and only the registry requirement remains. The header of the normalized `Cargo.toml` in the package notes that `path` dependencies are rewritten to registry dependencies, and the original is kept as `Cargo.toml.orig`. ## What `cargo publish` demands `cargo publish` builds the `.crate` the same way `cargo package` does, so the failures show up locally: - A normal or build dependency with only `path` or only `git` fails with "all dependencies must have a version requirement specified when packaging", plus a note that the packaged dependency will use the version from crates.io. - With a `version` added, packaging resolves that dependency **against the registry**; if the sibling crate was never published, it fails with "no matching package named `ledger-model` found". Publish the sibling first, then the crate that depends on it. - crates.io does not allow dependencies on code published outside crates.io, with dev-dependencies excepted; a path-only dev-dependency is simply dropped from the packaged manifest. The git case needs the most care. Writing `version = "1.4"` beside a `rev` gets the line past the packaging check, but the published crate is then built against the registry's 1.4.x release, **not** the commit you tested with. If the `rev` carries an unreleased fix, the published crate ships without it. The honest options are to wait for an upstream release that contains the fix, or to publish the fork under its own package name and depend on that release. ## A review checklist | Line | Local build | Publishable to crates.io? | |---|---|---| | `{ path = "crates/ledger-model" }` | builds the folder | no, needs a version | | `{ path = "...", version = "0.4" }` | builds the folder, checks ^0.4 | yes, once 0.4.x is published | | `{ git = "...", rev = "4c59b707" }` | builds the locked commit | no | | `{ git = "...", rev = "...", version = "1.4" }` | builds the commit, checks ^1.4 | yes, but users get the registry release |

  • The git dependency uses `branch = "main"` instead of `rev`. When does the build pick up new commits on main?
    Only when someone runs `cargo update` (for that package or the whole graph). Cargo records the commit in `Cargo.lock` when the dependency is added and reuses it on every later build, so a branch dependency is reproducible until the lockfile is updated, while a commit-hash `rev` keeps the same commit even then.
  • Why does `ledger-model = { path = "crates/ledger-model", version = "0.4" }` fail locally after a teammate bumps the sibling crate to 0.5.0?
    Cargo checks the local copy's version against the requirement whenever `version` sits beside `path`. Under the caret rule `"0.4"` means `>=0.4.0, <0.5.0`, so 0.5.0 does not match and Cargo reports that it failed to select a version. The requirement must be raised to `"0.5"` in the same change.
  • Can a published crate keep a path dependency that only its tests use?
    Yes, if it is listed under `[dev-dependencies]`. crates.io's rule against non-registry dependencies excludes dev-dependencies, and when packaging Cargo keeps only dev-dependencies that specify a version, so a path-only one is dropped. The Cargo book still suggests giving dev-dependencies a version where possible, because some users, such as OS packagers, run a published crate's tests.

  • A git dependency is re-fetched at the newest commit on every build.
  • With version beside path, Cargo builds the registry release locally.
  • Adding version beside rev publishes the crate with the pinned git commit.
  • Cargo searches subfolders of a path dependency to find the crate.
  • branch and rev can be combined to pin a commit on a branch.
  • crates.io accepts git dependencies as long as rev is a full commit hash.