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

gix_dir/
lib.rs
