feat!: start blame from Start instead of ObjectId

[Christoph Rüßler (cruessler)]

This PR changes gix_blame::file()’s API to use Start as the starting point instead of a simple ObjectId. Start can be either a Commit or Contents { first_suspect: ObjectId, contents: Cow<'_, u8> }. This is useful when callers have a version of the file that is not committed yet.

This PR potentially addresses #2666 if changes to gix_blame::file() are sufficient. This PR neither changes Repository::blame_file nor gix blame …; both use Start::Commit to keep their existing behaviour. I plan on adding support for Start::Contents to both in follow-up PRs. Do you potentially have any suggestions on how to get the worktree version of a file as idiomatically as possible? Is this something Platform::set_resource should be used for?

Update 2026-07-19: I’ve adapted gix blame …, in order to provide an example for how to load a file from the worktree and convert it to a diffable Vec<u8>.

This PR also affects #2457 as it changes some of the same locations, but I think the resulting conflicts should be manageable.

This PR was made with the help of an LLM, mostly for inspiration and getting an overview of the problem space, but also for some initial blocks of code (that I then reworked).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9127f126d7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "Codex (@codex) address that feedback".

[Christoph Rüßler (cruessler)]

Would it make sense to add a test for high-level gix blame … behaviour at the command-line level? From what I remember, you generally consider CLI behaviour unstable and prefer not to add tests. Is that still the case?

[Sebastian Thiel (Byron)]

you generally consider CLI behaviour unstable and prefer not to add tests. Is that still the case?

Yes, that's correct. If there should be tests, they have to be in plumbing or gix (crate).
Lastly, what I noticed that agents like to write tests in gitoxide-core for faster turnaround times, and that's fine, I just delete them when they are done and I could run it successfully once or twice.