feat!: Add experimental notion of *precious* files.

*Precious* files are ignored files, but those that are not expendable.
By default, all ignored files are expendable, but now it's possible to
declare ignored files as precious, meaning they will not be removed
just like untracked files.

See [the technical document][1] for details.

[1]: newren/git@0e6e3a6?diff=unified&w=0

Author: Byron

Cargo.lock

@@ -19,6 +19,7 @@ serde = ["dep:serde", "bstr/serde", "gix-glob/serde"]
 [dependencies]
 gix-glob = { version = "^0.14.1", path = "../gix-glob" }
 gix-path = { version = "^0.10.1", path = "../gix-path" }
+gix-trace = { version = "^0.1.4", path = "../gix-trace" }
 
 bstr = { version = "1.3.0", default-features = false, features = ["std", "unicode"]}
 unicode-bom = "2.0.2"

gix-ignore/Cargo.toml

@@ -25,6 +25,25 @@ pub struct Search {
     pub patterns: Vec<gix_glob::search::pattern::List<search::Ignore>>,
 }
 
+/// The kind of *ignored* item.
+///
+/// This classification is obtained when checking if a path matches an ignore pattern.
+#[derive(Default, Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Debug)]
+pub enum Kind {
+    /// The item is ignored and will be removed to make place for tracked items that are to be checked out.
+    ///
+    /// This is the default for ignored items.
+    /// Another way of thinking about this class is to consider these files *trashable*, or talk about them as `ignored-and-expendable`.
+    #[default]
+    Expendable,
+    /// An ignored file was additionally marked as *precious* using the `$` prefix to indicate the file shall be kept.
+    ///
+    /// This means that precious files are treated like untracked files, which also must not be removed, but won't show up by default
+    /// as they are also ignored.
+    /// One can also talk about them as `ignored-and-precious`.
+    Precious,
+}
+
 ///
 pub mod parse;
 

gix-ignore/src/lib.rs

@@ -18,17 +18,43 @@ impl<'a> Lines<'a> {
 }
 
 impl<'a> Iterator for Lines<'a> {
-    type Item = (gix_glob::Pattern, usize);
+    type Item = (gix_glob::Pattern, usize, crate::Kind);
 
     fn next(&mut self) -> Option<Self::Item> {
-        for line in self.lines.by_ref() {
+        for mut line in self.lines.by_ref() {
             self.line_no += 1;
-            if line.first() == Some(&b'#') {
-                continue;
-            }
-            match gix_glob::Pattern::from_bytes(truncate_non_escaped_trailing_spaces(line)) {
+            let first = match line.first().copied() {
+                Some(b'#') | None => continue,
+                Some(c) => c,
+            };
+            let (kind, can_negate) = if first == b'$' {
+                line = &line[1..];
+                (crate::Kind::Precious, false)
+            } else {
+                let second = line.get(1);
+                if first == b'!' && second == Some(&b'$') {
+                    gix_trace::error!(
+                        "Line {} starts with !$ which is not allowed ('{}')",
+                        self.line_no,
+                        line.as_bstr()
+                    );
+                    continue;
+                }
+                if first == b'\\' && second == Some(&b'$') {
+                    line = &line[1..];
+                }
+                (crate::Kind::Expendable, true)
+            };
+
+            line = truncate_non_escaped_trailing_spaces(line);
+            let res = if can_negate {
+                gix_glob::Pattern::from_bytes(line)
+            } else {
+                gix_glob::Pattern::from_bytes_without_negation(line)
+            };
+            match res {
                 None => continue,
-                Some(pattern) => return Some((pattern, self.line_no)),
+                Some(pattern) => return Some((pattern, self.line_no, kind)),
             }
         }
         None

gix-ignore/src/parse.rs

@@ -15,6 +15,8 @@ pub struct Match<'a> {
     pub pattern: &'a gix_glob::Pattern,
     /// The path to the source from which the pattern was loaded, or `None` if it was specified by other means.
     pub source: Option<&'a Path>,
+    /// The kind of pattern this match represents.
+    pub kind: crate::Kind,
     /// The line at which the pattern was found in its `source` file, or the occurrence in which it was provided.
     pub sequence_number: usize,
 }
@@ -24,13 +26,13 @@ pub struct Match<'a> {
 pub struct Ignore;
 
 impl Pattern for Ignore {
-    type Value = ();
+    type Value = crate::Kind;
 
     fn bytes_to_patterns(bytes: &[u8], _source: &std::path::Path) -> Vec<pattern::Mapping<Self::Value>> {
         crate::parse(bytes)
-            .map(|(pattern, line_number)| pattern::Mapping {
+            .map(|(pattern, line_number, kind)| pattern::Mapping {
                 pattern,
-                value: (),
+                value: kind,
                 sequence_number: line_number,
             })
             .collect()
@@ -61,7 +63,7 @@ impl Search {
         Ok(group)
     }
 
-    /// Parse a list of patterns, using slashes as path separators
+    /// Parse a list of ignore patterns, using slashes as path separators.
     pub fn from_overrides(patterns: impl IntoIterator<Item = impl Into<OsString>>) -> Self {
         Self::from_overrides_inner(&mut patterns.into_iter().map(Into::into))
     }
@@ -73,11 +75,13 @@ impl Search {
                     .enumerate()
                     .filter_map(|(seq_id, pattern)| {
                         let pattern = gix_path::try_into_bstr(PathBuf::from(pattern)).ok()?;
-                        gix_glob::parse(pattern.as_ref()).map(|p| pattern::Mapping {
-                            pattern: p,
-                            value: (),
-                            sequence_number: seq_id,
-                        })
+                        crate::parse(pattern.as_ref())
+                            .next()
+                            .map(|(p, _seq_id, kind)| pattern::Mapping {
+                                pattern: p,
+                                value: kind,
+                                sequence_number: seq_id + 1,
+                            })
                     })
                     .collect(),
                 source: None,
@@ -112,7 +116,7 @@ pub fn pattern_matching_relative_path<'a>(
     list.patterns.iter().rev().find_map(
         |pattern::Mapping {
              pattern,
-             value: (),
+             value: kind,
              sequence_number,
          }| {
             pattern
@@ -125,6 +129,7 @@ pub fn pattern_matching_relative_path<'a>(
                 )
                 .then_some(Match {
                     pattern,
+                    kind: *kind,
                     source: list.source.as_deref(),
                     sequence_number: *sequence_number,
                 })

gix-ignore/src/search.rs

@@ -0,0 +1,12 @@
+$.config
+\$starts-with-dollar
+# html files are now precious and won't be discarded
+$*.html
+
+!foo.html
+
+# this isn't allowed and ignored
+!$foo.html
+
+# but this is a literal !/* that is precious
+$!/*

gix-ignore/tests/fixtures/ignore/precious.txt

@@ -2,6 +2,22 @@ use bstr::BString;
 use gix_glob::{pattern::Mode, Pattern};
 use gix_testtools::fixture_bytes;
 
+#[test]
+fn precious() {
+    let input = fixture_bytes("ignore/precious.txt");
+    let actual: Vec<_> = gix_ignore::parse(&input).map(flat_map).collect();
+    assert_eq!(
+        actual,
+        vec![
+            pat_precious(".config", Mode::NO_SUB_DIR, 1),
+            pat("$starts-with-dollar", Mode::NO_SUB_DIR, 2),
+            pat_precious("*.html", Mode::NO_SUB_DIR | Mode::ENDS_WITH, 4),
+            pat("foo.html", Mode::NO_SUB_DIR | Mode::NEGATIVE, 6),
+            pat_precious("!/*", Mode::empty(), 12),
+        ]
+    );
+}
+
 #[test]
 fn byte_order_marks_are_no_patterns() {
     assert_eq!(
@@ -58,7 +74,7 @@ fn backslashes_before_hashes_are_no_comments() {
 
 #[test]
 fn trailing_spaces_can_be_escaped_to_be_literal() {
-    fn parse_one(input: &str) -> (BString, Mode, usize) {
+    fn parse_one(input: &str) -> (BString, Mode, usize, gix_ignore::Kind) {
         let actual: Vec<_> = gix_ignore::parse(input.as_bytes()).map(flat_map).collect();
         assert_eq!(actual.len(), 1, "{input:?} should match");
         actual.into_iter().next().expect("present")
@@ -101,14 +117,20 @@ fn trailing_spaces_can_be_escaped_to_be_literal() {
     );
 }
 
-fn flatten(input: Option<(Pattern, usize)>) -> Option<(BString, gix_glob::pattern::Mode, usize)> {
+fn flatten(
+    input: Option<(Pattern, usize, gix_ignore::Kind)>,
+) -> Option<(BString, gix_glob::pattern::Mode, usize, gix_ignore::Kind)> {
     input.map(flat_map)
 }
 
-fn flat_map(input: (Pattern, usize)) -> (BString, gix_glob::pattern::Mode, usize) {
-    (input.0.text, input.0.mode, input.1)
+fn flat_map(input: (Pattern, usize, gix_ignore::Kind)) -> (BString, gix_glob::pattern::Mode, usize, gix_ignore::Kind) {
+    (input.0.text, input.0.mode, input.1, input.2)
+}
+
+fn pat(pattern: &str, mode: Mode, pos: usize) -> (BString, Mode, usize, gix_ignore::Kind) {
+    (pattern.into(), mode, pos, gix_ignore::Kind::Expendable)
 }
 
-fn pat(pattern: &str, mode: Mode, pos: usize) -> (BString, Mode, usize) {
-    (pattern.into(), mode, pos)
+fn pat_precious(pattern: &str, mode: Mode, pos: usize) -> (BString, Mode, usize, gix_ignore::Kind) {
+    (pattern.into(), mode, pos, gix_ignore::Kind::Precious)
 }

gix-ignore/tests/parse/mod.rs

@@ -81,6 +81,7 @@ fn baseline_from_git_dir() -> crate::Result {
                     sequence_number,
                     pattern: _,
                     source,
+                    kind: gix_ignore::Kind::Expendable,
                 }),
                 Some((expected_source, line, _expected_pattern)),
             ) => {
@@ -100,28 +101,66 @@ fn baseline_from_git_dir() -> crate::Result {
 }
 
 #[test]
-fn from_overrides() {
-    let input = ["simple", "pattern/"];
+fn from_overrides_with_precious() {
+    let input = ["$s?mple", "pattern/"];
     let group = gix_ignore::Search::from_overrides(input.iter());
+
+    assert_eq!(
+        group.pattern_matching_relative_path("Simple".into(), None, gix_glob::pattern::Case::Fold),
+        Some(pattern_to_match(
+            &gix_glob::parse("s?mple").unwrap(),
+            1,
+            gix_ignore::Kind::Precious
+        )),
+        ""
+    );
+}
+
+#[test]
+fn from_overrides_with_excludes() {
+    let group = gix_ignore::Search::from_overrides(["$simple", "!simple", "pattern/"]);
+    assert_eq!(
+        group.pattern_matching_relative_path("Simple".into(), None, gix_glob::pattern::Case::Fold),
+        Some(pattern_to_match(
+            &gix_glob::parse("!simple").unwrap(),
+            2,
+            gix_ignore::Kind::Expendable
+        )),
+        "Now the negative pattern matches - the sequence numbers are 1-based"
+    );
+}
+
+#[test]
+fn from_overrides() {
+    let group = gix_ignore::Search::from_overrides(["simple", "pattern/"]);
     assert_eq!(
         group.pattern_matching_relative_path("Simple".into(), None, gix_glob::pattern::Case::Fold),
-        Some(pattern_to_match(&gix_glob::parse("simple").unwrap(), 0))
+        Some(pattern_to_match(
+            &gix_glob::parse("simple").unwrap(),
+            1,
+            gix_ignore::Kind::Expendable
+        ))
     );
     assert_eq!(
         group.pattern_matching_relative_path("pattern".into(), Some(true), gix_glob::pattern::Case::Sensitive),
-        Some(pattern_to_match(&gix_glob::parse("pattern/").unwrap(), 1))
+        Some(pattern_to_match(
+            &gix_glob::parse("pattern/").unwrap(),
+            2,
+            gix_ignore::Kind::Expendable
+        ))
     );
     assert_eq!(group.patterns.len(), 1);
     assert_eq!(
-        gix_ignore::Search::from_overrides(input).patterns[0],
+        gix_ignore::Search::from_overrides(["simple", "pattern/"]).patterns[0],
         group.patterns.into_iter().next().unwrap()
     );
 }
 
-fn pattern_to_match(pattern: &gix_glob::Pattern, sequence_number: usize) -> Match<'_> {
+fn pattern_to_match(pattern: &gix_glob::Pattern, sequence_number: usize, kind: gix_ignore::Kind) -> Match<'_> {
     Match {
         pattern,
         source: None,
         sequence_number,
+        kind,
     }
 }