gix_ignore/
lib.rs

1//! Parse `.gitignore` files and provide utilities to match against them.
2//!
3//! ## Examples
4//!
5//! ```
6//! use gix_glob::pattern::Case;
7//!
8//! let search = gix_ignore::Search::from_overrides(["target/", "!target/keep.me"], Default::default());
9//!
10//! let ignored = search
11//!     .pattern_matching_relative_path("target".into(), Some(true), Case::Sensitive)
12//!     .unwrap();
13//! assert_eq!(ignored.sequence_number, 1);
14//! assert_eq!(ignored.kind, gix_ignore::Kind::Expendable);
15//! assert!(!ignored.pattern.is_negative());
16//!
17//! let kept = search
18//!     .pattern_matching_relative_path("target/keep.me".into(), Some(false), Case::Sensitive)
19//!     .unwrap();
20//! assert_eq!(kept.sequence_number, 2);
21//! assert!(kept.pattern.is_negative());
22//! ```
23//!
24//! ## Feature Flags
25#![cfg_attr(
26    all(doc, feature = "document-features"),
27    doc = ::document_features::document_features!()
28)]
29#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg))]
30#![deny(missing_docs, rust_2018_idioms)]
31#![forbid(unsafe_code)]
32
33pub use gix_glob as glob;
34
35///
36pub mod search;
37/// A grouping of lists of patterns while possibly keeping associated to their base path in order to find matches.
38///
39/// Pattern lists with base path are queryable relative to that base, otherwise they are relative to the repository root.
40#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Default)]
41pub struct Search {
42    /// A list of pattern lists, each representing a patterns from a file or specified by hand, in the order they were
43    /// specified in.
44    ///
45    /// When matching, this order is reversed.
46    pub patterns: Vec<gix_glob::search::pattern::List<search::Ignore>>,
47}
48
49/// The kind of *ignored* item.
50///
51/// This classification is obtained when checking if a path matches an ignore pattern.
52#[derive(Default, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Debug)]
53pub enum Kind {
54    /// The item is ignored and will be removed to make place for tracked items that are to be checked out.
55    ///
56    /// This is the default for ignored items.
57    /// Another way of thinking about this class is to consider these files *trashable*, or talk about them as `ignored-and-expendable`.
58    #[default]
59    Expendable,
60    /// An ignored file was additionally marked as *precious* using the `$` prefix to indicate the file shall be kept.
61    ///
62    /// This means that precious files are treated like untracked files, which also must not be removed, but won't show up by default
63    /// as they are also ignored.
64    /// One can also talk about them as `ignored-and-precious`.
65    Precious,
66}
67
68///
69pub mod parse;
70
71/// Parse git ignore patterns, line by line, from `bytes`.
72///
73/// If `support_precious` is `true`, we will parse `$` prefixed entries as precious.
74/// This is backward-incompatible as files that actually start with `$` like `$houdini`
75/// will then not be ignored anymore, instead it ignores `houdini`.
76pub fn parse(bytes: &[u8], support_precious: bool) -> parse::Lines<'_> {
77    parse::Lines::new(bytes, support_precious)
78}
gix_ignore/lib.rs

gix_ignore/
lib.rs
