doc: Document executable-bit behavior during checkout

[shvvkz]

Reported issue

checkout::Options::overwrite_existing currently documents that existing worktree entries won't be overwritten unless the option is enabled. However, it doesn't mention that in a non-exclusive checkout, pre-existing files may still have their executable bit updated to match the index even when overwrite_existing is false.

This can be surprising because callers may interpret overwrite_existing = false as preventing all changes to existing files, while the current behavior only prevents overwriting file contents.

Closes #1787.

Summary

• Clarified the documentation for checkout::Options::overwrite_existing.
• Documented that when destination_is_initially_empty is false, existing files may still receive executable-bit updates even if overwrite_existing is false.
• Left the checkout behavior unchanged.

Validation

• cargo fmt

I also tried to run cargo check -p gix-worktree-state, but it failed while compiling gix-hash without hash features, which appears unrelated to this documentation-only change.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR clarifies the behavior of Options::overwrite_existing during checkout, specifically that metadata (like the executable bit) may still be updated even when file contents are not overwritten.

Changes:

• Expanded the doc comment for overwrite_existing to document a metadata-update edge case
• Clarified interaction with destination_is_initially_empty

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 47fbe95a42

ℹ️ About Codex in GitHub

Your team has set up Codex to 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 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".