Merge pull request #2555 from GitoxideLabs/index-docs

improve gix-index docs

Author: Byron

COLLABORATING.md

@@ -16,6 +16,15 @@
     - …and you _do know_ the cause, please fix it immediately. If necessary by reverting the offending commit until a more durable fix is possible.
     - …and you _do not know_ the cause, please open a PR to invite collaborators for their input. This is to avoid multiple collaborators
       trying to fix the issue independently, causing merge-conflicts and confusion. We use this PR as synchronization primitive.
+- **please disclose AI assistance when collaborating**
+   - if AI edits files for you, disclose it in the PR description and commit metadata, preferably with an AI author
+     such as `$agent $version <ai-agent@example.invalid>` or a `Co-authored-by: <agent-identity>` trailer.
+   - agents operating through a person's GitHub account must identify themselves in comments, for example with phrases
+     like `AI agent on behalf of <person>: ...`.
+   - fully AI-generated PR or issue comments must be disclosed. Undisclosed AI-generated comments may lead to the PR or
+     issue being closed.
+   - AI-assisted proofreading or wording polish does not need disclosure, but it is still courteous to mention it when
+     the AI materially influenced the final text.
 - **for crates _you own_**
     - feel free to make any kind of changes to it, including major ones.
     - please use `cargo smart-release` for publishing to crates.io as it will handle dependencies properly.

CONTRIBUTING.md

@@ -1,7 +1,18 @@
-### Please disclose the use AI…
+### Please disclose the use of AI
 
-…if it's editing files for you please let us know in the PR comment _or preferably_ using
-`Co-authored-by: <agent-identity>` message trailers.
+If AI edits files for you, disclose it in the PR description and commit metadata. Prefer making the
+agent identity part of the commit, for example by using an AI *author* such as `$agent $version <ai-agent@example.invalid>`
+or a *co-author* via `Co-authored-by: <agent-identity>` trailer.
+Recent commits in this repository use that pattern, often with a *human* `Co-authored-by` trailer when a person also contributed directly.
+
+Agents operating through a person's GitHub account must identify themselves. For example, comments
+posted by an agent should say so directly with phrases like `AI agent on behalf of <person>: ...`.
+
+Fully AI-generated comments on PRs or issues must also be disclosed. Undisclosed AI-generated
+comments may lead to the PR or issue being closed.
+
+AI-assisted proofreading or wording polish does not need disclosure, but it is still courteous to
+mention it when the AI materially influenced the final text.
 
 For everything else, please have a look at the respective section in the [README] file.
 

README.md

@@ -348,8 +348,10 @@ We recommend running `just test` during the development process to assure CI is
 A backlog for work ready to be picked up is [available in the Project's Kanban board][project-board], which contains instructions on how
 to pick a task. If it's empty or you have other questions, feel free to [start a discussion][discussions] or reach out to @Byron [privately][keybase].
 
-For additional details, also take a look at the [collaboration guide].
+For additional details, also take a look at the [collaboration guide]. If AI participates in a contribution, please
+follow the [AI disclosure requirements]. "Full-auto" contributions without a human on the other end may be closed unceremoniously.
 
+[AI disclosure requirements]: https://github.com/GitoxideLabs/gitoxide/blob/main/CONTRIBUTING.md#please-disclose-the-use-of-ai
 [collaboration guide]: https://github.com/GitoxideLabs/gitoxide/blob/main/COLLABORATING.md
 [project-board]: https://github.com/GitoxideLabs/gitoxide/projects
 [discussions]: https://github.com/GitoxideLabs/gitoxide/discussions

gix-index/src/access/mod.rs

@@ -69,8 +69,9 @@ impl State {
         })
     }
 
-    /// Find the entry index in [`entries()`][State::entries()] matching the given repository-relative
-    /// `path` and `stage`, or `None`.
+    /// Find the entry index in [`entries()`][State::entries()] matching the given `path` and `stage`, or `None`.
+    ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
     ///
     /// Use the index for accessing multiple stages if they exists, but at least the single matching entry.
     pub fn entry_index_by_path_and_stage(&self, path: &BStr, stage: entry::Stage) -> Option<usize> {
@@ -194,6 +195,8 @@ impl State {
     /// Return the entry at `path` that is at the lowest available stage, using `lookup` for acceleration.
     /// It must have been created from this instance, and was ideally kept up-to-date with it.
     ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// If `ignore_case` is `true`, a case-insensitive (ASCII-folding only) search will be performed.
     pub fn entry_by_path_icase<'a>(
         &'a self,
@@ -219,6 +222,8 @@ impl State {
     /// Return the entry (at any stage) that is inside `directory`, or `None`,
     /// or a directory itself like a submodule or sparse directory, using `lookup` for acceleration.
     ///
+    /// The `directory` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// If `ignore_case` is set, a case-insensitive (ASCII-folding only) search will be performed.
     pub fn entry_closest_to_directory_or_directory_icase<'a>(
         &'a self,
@@ -244,6 +249,8 @@ impl State {
     /// Return the entry (at any stage) that is inside `directory`, or `None`,
     /// or that is a directory itself like a submodule or sparse directory.
     ///
+    /// The `directory` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// Note that this is a *case-sensitive* search.
     pub fn entry_closest_to_directory_or_directory(&self, directory: &BStr) -> Option<&Entry> {
         let idx = match self.entry_index_by_path(directory) {
@@ -272,6 +279,8 @@ impl State {
 
     /// Check if `path` is a directory that contains entries in the index, or is a submodule.
     ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// Returns `true` if there is at least one entry in the index whose path starts with `path/`,
     /// indicating that `path` is a directory containing indexed files.
     ///
@@ -286,6 +295,8 @@ impl State {
     /// Check if `path` is a directory that contains entries in the index or is a submodule,
     /// with optional case-insensitive matching.
     ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// Returns `true` if there is at least one entry in the index whose path starts with `path/`,
     /// indicating that `path` is a directory containing indexed files.
     ///
@@ -304,8 +315,10 @@ impl State {
             .is_some()
     }
 
-    /// Find the entry index in [`entries()[..upper_bound]`][State::entries()] matching the given repository-relative
-    /// `path` and `stage`, or `None`.
+    /// Find the entry index in [`entries()[..upper_bound]`][State::entries()] matching the given `path` and `stage`,
+    /// or `None`.
+    ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
     ///
     /// Use the index for accessing multiple stages if they exists, but at least the single matching entry.
     ///
@@ -325,13 +338,17 @@ impl State {
 
     /// Like [`entry_index_by_path_and_stage()`](State::entry_index_by_path_and_stage()),
     /// but returns the entry instead of the index.
+    ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
     pub fn entry_by_path_and_stage(&self, path: &BStr, stage: entry::Stage) -> Option<&Entry> {
         self.entry_index_by_path_and_stage(path, stage)
             .map(|idx| &self.entries[idx])
     }
 
     /// Return the entry at `path` that is either at stage 0, or at stage 2 (ours) in case of a merge conflict.
     ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// Using this method is more efficient in comparison to doing two searches, one for stage 0 and one for stage 2.
     pub fn entry_by_path(&self, path: &BStr) -> Option<&Entry> {
         let mut stage_at_index = 0;
@@ -355,19 +372,25 @@ impl State {
 
     /// Return the index at `Ok(index)` where the entry matching `path` (in any stage) can be found, or return
     /// `Err(index)` to indicate the insertion position at which an entry with `path` would fit in.
+    ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
     pub fn entry_index_by_path(&self, path: &BStr) -> Result<usize, usize> {
         self.entries.binary_search_by(|e| e.path(self).cmp(path))
     }
 
     /// Return the slice of entries which all share the same `prefix`, or `None` if there isn't a single such entry.
     ///
+    /// The `prefix` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// If `prefix` is empty, all entries are returned.
     pub fn prefixed_entries(&self, prefix: &BStr) -> Option<&[Entry]> {
         self.prefixed_entries_range(prefix).map(|range| &self.entries[range])
     }
 
     /// Return the range of entries which all share the same `prefix`, or `None` if there isn't a single such entry.
     ///
+    /// The `prefix` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// If `prefix` is empty, the range will include all entries.
     pub fn prefixed_entries_range(&self, prefix: &BStr) -> Option<Range<usize>> {
         if prefix.is_empty() {
@@ -415,6 +438,8 @@ impl State {
     /// Return the range of entries that exactly match the given `path`, in all available stages, or `None` if no entry with such
     /// path exists.
     ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// The range can be used to access the respective entries via [`entries()`](Self::entries()) or [`entries_mut()](Self::entries_mut()).
     pub fn entry_range(&self, path: &BStr) -> Option<Range<usize>> {
         let mut stage_at_index = 0;
@@ -506,6 +531,8 @@ impl State {
 
     /// Like [`entry_index_by_path_and_stage()`][State::entry_index_by_path_and_stage()],
     /// but returns the mutable entry instead of the index.
+    ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
     pub fn entry_mut_by_path_and_stage(&mut self, path: &BStr, stage: entry::Stage) -> Option<&mut Entry> {
         self.entry_index_by_path_and_stage(path, stage)
             .map(|idx| &mut self.entries[idx])
@@ -515,6 +542,8 @@ impl State {
     /// any sanity checks. This means it's possible to push a new entry to the same path on the same stage and even after sorting
     /// the entries lookups may still return the wrong one of them unless the correct binary search criteria is chosen.
     ///
+    /// The `path` must use the repository-relative, slash-separated [`State`] path format.
+    ///
     /// Note that this *is likely* to break invariants that will prevent further lookups by path unless
     /// [`entry_index_by_path_and_stage_bounded()`][State::entry_index_by_path_and_stage_bounded()] is used with
     /// the `upper_bound` being the amount of entries before the first call to this method.

gix-index/src/lib.rs

@@ -112,6 +112,12 @@ pub struct AccelerateLookup<'a> {
 /// As opposed to a snapshot, it's meant to be altered and eventually be written back to disk or converted into a tree.
 /// We treat index and its state synonymous.
 ///
+/// # Path Format
+///
+/// All entry paths stored by [`State`], and all path-like arguments used to access entries, are repository-relative byte
+/// strings with `/` as separator. They are not platform-native filesystem paths, must not be absolute, and must not use
+/// separators like `\`; convert worktree or absolute paths to this representation before lookup or insertion.
+///
 /// # A note on safety
 ///
 /// An index (i.e. [`State`]) created by hand is not guaranteed to have valid entry paths as they are entirely controlled