gix integration breaks doc building

[nerditation]

to be honest, until I encountered this problem, I didn't know about gix, but it seems to cause problem when I build docs. below is the commands to reproduce this error:

❯ echo $env.PROCESSOR_ARCHITECTURE
AMD64

❯ ver

Microsoft Windows [Version 10.0.19045.4412]

❯ cargo --version
cargo 1.80.0-nightly (4de0094ac 2024-05-09)

❯ cargo new --lib dummy
    Creating library `dummy` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

❯ cd dummy\

❯ git add .

❯ cargo doc
error: failed to determine package fingerprint for documenting dummy v0.1.0 (Y:\dummy)

Caused by:
  failed to determine the most recently modified file in Y:\dummy

Caused by:
  failed to determine list of files in Y:\dummy

Caused by:
  The value for `core.excludesFile` could not be read from configuration

Caused by:
  path is missing

by grepping through the code base for the error messages and some experiments, I managed to pinpoint the failed code is at this line, where the repo.walkdir_iter() method returns Err:

cargo/src/cargo/sources/path.rs

Line 519 in 8d68ed4

.dirwalk_iter(index.clone(), pathspec, Default::default(), options)?

I did some investigation of the gix code, and it turns out my git config file contains a blank value for core.excludesfile which gix treats differently than a missing core.excludesfile entry.

I opened an issue for gix GitoxideLabs/gitoxide#1370, but I want to at least mention it here, in case someone else enountered similar problem and want to search for reasons.

also, I'm not sure if this is considered a bug for gix or not, but at least it behaves differently from libgit2. when I browse the source code of cargo here:

cargo/src/cargo/sources/path.rs

Lines 145 to 155 in 8d68ed4

	if self
	.gctx
	.get_env("__CARGO_GITOXIDE_DISABLE_LIST_FILES")
	.ok()
	.as_deref()
	== Some("1")
	{
	self.discover_git_repo(root)?.map(Git2OrGixRepository::Git2)
	} else {
	self.discover_gix_repo(root)?.map(Git2OrGixRepository::Gix)
	}

I discovered this __CARGO_GITOXIDE_DISABLE_LIST_FILES environment variable )(undocumented anywhere) so I tried to set it, and then cargo doc runs without showing any errors.

[Byron]

The fix for this is in this PR, and it works by adding lenient_config support to all paths gitoxide would encounter. Previously, it would always reject empty paths, but now it will ignore these.

Note that the repository is opened with default options, which uses the lenient_config mode by default. This also means that in its current form, cargo depends on a default value, but it's one that I don't intend to change.

Lastly, I plan to create a new release in the coming week and hope I will do my best to not forget to upgrade gix here.

[nerditation]

thanks for the quick response and insights.

one thing is still not clear to me though: I only get this error when I do cargo doc, but other sub commands (check, build, run, fmt, etc.) are not affected at all. I wonder if the doc command triggers this by accident, or is it fundamental different how doc works than the other commands?

[weihanglo]

There are some nuances between normal cargo build and cargo doc. For each rustc invocation, Cargo requests for dep-info files to deteremine when to rebuild. However, rustdoc doesn't have the equivalent functionality (yet), so the best-effort solution for now is walking through the file system and record the latest file modified time.

See also the Cargo internal doc for fingerprint.

[weihanglo]

GitoxideLabs/gitoxide#1371 has been merged. The next step is waiting for a new release, and determine if we want a beta backport before Gitoxide integration hits stable.

[weihanglo]

Close as #13948 should have resolved this. The new nightly cargo should come out on this Friday/Saturday. Let us know if the issue persists then.