docs(gix-index): improve docs to make clear they need repo-relative slash separated paths.

Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

Author: codex

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