sxyazi/yazi · error

Git symlink target escapes repository: `{}`

Error message

Git symlink target escapes repository: `{}`

What it means

Safety guard while materializing git symlinks: a symlink's canonicalized target resolved outside the repository root, which the package manager refuses to materialize to prevent a checkout from writing outside its own directory. The faulting input is the symlink target recorded in the repo (`original` after canonicalization).

Source

Thrown at yazi-cli/src/package/git.rs:82

			let Some(tab) = ent.iter().position(|&b| b == b'\t') else { continue };
			let link = path.join(
				Path::from_wtf8(&ent[tab + 1..]).context("Git path cannot be represented by the OS")?,
			);

			let is_symlink = fs::symlink_metadata(&link).await?.file_type().is_symlink();
			let original = if is_symlink {
				fs::read_link(&link).await? // TODO: compat for old caches, remove in the future
			} else {
				PathBuf::from_wtf8_vec(fs::read(&link).await?)
					.context("Git symlink origin cannot be represented by the OS")?
			};
			let original = fs::canonicalize(link.parent().unwrap_or(&path).join(original))
				.await
				.with_context(|| format!("failed to resolve Git symlink target `{}`", link.display()))?;

			if !original.starts_with(&path) {
				bail!("Git symlink target escapes repository: `{}`", link.display());
			} else if is_symlink {
				fs::remove_file(&link).await?;
			}

			fs::copy(original, &link)
				.await
				.with_context(|| format!("failed to materialize `{}`", link.display()))?;
		}

		Ok(())
	}

	async fn exec(f: impl FnOnce(&mut Command) -> &mut Command) -> Result<()> {
		let status = f(Command::new("git").args([
			"-c",
			"core.eol=lf",
			"-c",
			"core.autocrlf=false",

View on GitHub (pinned to 5f901b886b)

Solutions

1. Audit the package's symlinks; fix or remove ones pointing outside the repository.
2. Report the offending package to its maintainer if it ships escaping symlinks.
3. Avoid installing packages with untrusted symlink content.

When it happens

Trigger: Thrown at yazi-cli/src/package/git.rs:82 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of sxyazi/yazi@5f901b886b (2026-09-02). Data as JSON: /api/errors/fd2ef5d8d3e0f6be. Report an issue: GitHub.