git-fetch-with-cli: the Silver Bullet of Cargo Configuration Troubleshooting

Cargo can be configured to use the git executable to perform repository authentication, instead of the default, which uses libgit2:

# ~/.cargo/config.toml

[net]
git-fetch-with-cli = true

Changing this setting resolves a shockingly wide array of configuration problems.

The root issue is that Cargo uses libgit2 by default to interact with a registry index repository, which has known shortcomings as it relates to authentication. These shortcomings are fully acknowledged by the Cargo team, and modifying the git-fetch-with-cli setting is frequently put forward as a potential solution to users having trouble.

Honestly, do yourself a favor: for anything other than bog standard Cargo settings, set git-fetch-with-cli to true.

Here is an example error output from cargo login that was resolved by setting git-fetch-with-cli = true:

$ cargo login --registry shipyard-rs ${AUTH_TOKEN}

error: failed to update registry `shipyard-rs`

Caused by:
failed to fetch `ssh://git@ssh.shipyard.rs/shipyard-rs/crate-index.git`

Caused by:
failed to authenticate when downloading repository

* attempted ssh-agent authentication, but no usernames succeeded: `git`

if the git CLI succeeds then `net.git-fetch-with-cli` may help here
https://doc.rust-lang.org/cargo/reference/config.html#netgit-fetch-with-cli

Caused by:
no authentication available

Relation to CVE-2022-46176

On Jan. 10, the Rust team announced that Cargo was being patched to fix a security vulnerability relating to how it cloned git repositories over SSH.

One important aspect of the vulnerability is that it did not affect users who had set the git-fetch-with-cli setting to true, which prompts Cargo to use the local git binary to perform clones over SSH.