gix_dir/
lib.rs

1//! A crate for handling a git-style directory walk.
2#![deny(missing_docs, rust_2018_idioms)]
3#![forbid(unsafe_code)]
4
5use std::borrow::Cow;
6
7use bstr::{BStr, BString};
8
9/// A directory entry, typically obtained using [`walk()`].
10#[derive(Debug, Clone, PartialEq, Eq, Hash, Ord, PartialOrd)]
11pub struct EntryRef<'a> {
12    /// The repository-relative path at which the file or directory could be found, with unix-style component separators.
13    ///
14    /// To obtain the respective file, join it with the `worktree_root` passed to [`walk()`].
15    /// The rationale here is that this is a compressed and normalized version compared to the paths we would otherwise get,
16    /// which is preferable especially when converted to [`Entry`] due to lower memory requirements.
17    ///
18    /// This also means that the original path to be presented to the user needs to be computed separately, as it's also relative
19    /// to their prefix, i.e. their current working directory within the repository.
20    ///
21    /// Note that this value can be empty if information about the `worktree_root` is provided, which is fine as
22    /// [joining](std::path::Path::join) with an empty string is a no-op.
23    ///
24    /// Note that depending on the way entries are emitted, even refs might already contain an owned `rela_path`, for use with
25    /// [into_owned()](EntryRef::into_owned())
26    ///
27    pub rela_path: Cow<'a, BStr>,
28    /// The status of entry, most closely related to what we know from `git status`, but not the same.
29    ///
30    /// Note that many entries with status `Pruned` will not show up as their kind hasn't yet been determined when they were
31    /// pruned very early on.
32    pub status: entry::Status,
33    /// Additional properties of the entry.
34    pub property: Option<entry::Property>,
35    /// Further specify what the entry is on disk, similar to a file mode.
36    /// This is `None` if we decided it's not worth it to exit early and avoid trying to obtain this information.
37    pub disk_kind: Option<entry::Kind>,
38    /// The kind of entry according to the index, if tracked. *Usually* the same as `disk_kind`.
39    pub index_kind: Option<entry::Kind>,
40    /// Determines how the pathspec matched.
41    /// Note that it can also be `Some(PathspecMatch::Excluded)` if a negative pathspec matched.
42    pub pathspec_match: Option<entry::PathspecMatch>,
43}
44
45/// Just like [`EntryRef`], but with all fields owned (and thus without a lifetime to consider).
46#[derive(Debug, Clone, PartialEq, Eq, Hash, Ord, PartialOrd)]
47pub struct Entry {
48    /// See [EntryRef::rela_path] for details.
49    pub rela_path: BString,
50    /// The status of entry, most closely related to what we know from `git status`, but not the same.
51    pub status: entry::Status,
52    /// Additional flags that further clarify properties of the entry.
53    pub property: Option<entry::Property>,
54    /// Further specify what the entry is on disk, similar to a file mode.
55    pub disk_kind: Option<entry::Kind>,
56    /// The kind of entry according to the index, if tracked. *Usually* the same as `disk_kind`.
57    /// Note that even if tracked, this might be `None` which indicates this is a worktree placed
58    /// within the parent repository.
59    pub index_kind: Option<entry::Kind>,
60    /// Indicate how the pathspec matches the entry. See more in [`EntryRef::pathspec_match`].
61    pub pathspec_match: Option<entry::PathspecMatch>,
62}
63
64///
65pub mod entry;
66
67///
68pub mod walk;
69pub use walk::function::walk;
gix_dir/lib.rs

gix_dir/
lib.rs
