Feat: Add --hierarchy flag for showing parent context lines

crates/core/flags/complete/rg.zsh

@@ -130,6 +130,9 @@ _rg() {
     '(pretty-vimgrep)--heading[show matches grouped by file name]'
     "(pretty-vimgrep)--no-heading[don't show matches grouped by file name]"
 
+    '(no-hierarchy)--hierarchy[print hierarchical parent lines for each match]'
+    '(hierarchy)--no-hierarchy[do not print hierarchical parent lines for each match]'
+
     + '(hidden)' # Hidden-file options
     {-.,--hidden}'[search hidden files and directories]'
     $no"--no-hidden[don't search hidden files and directories]"

crates/core/flags/defs.rs

@@ -77,6 +77,7 @@ pub(super) const FLAGS: &[&dyn Flag] = &[
     &Heading,
     &Help,
     &Hidden,
+    &Hierarchy,
     &HostnameBin,
     &HyperlinkFormat,
     &IGlob,
@@ -2832,6 +2833,61 @@ fn test_hidden() {
     assert_eq!(true, args.hidden);
 }
 
+#[derive(Debug)]
+struct Hierarchy;
+
+impl Flag for Hierarchy {
+    fn is_switch(&self) -> bool {
+        true
+    }
+    fn name_long(&self) -> &'static str {
+        "hierarchy"
+    }
+    fn name_negated(&self) -> Option<&'static str> {
+        Some("no-hierarchy")
+    }
+    fn doc_category(&self) -> Category {
+        Category::Output
+    }
+    fn doc_short(&self) -> &'static str {
+        r"adds a top-Level context line"
+    }
+    fn doc_long(&self) -> &'static str {
+        r"When enabled, ripgrep prints an additional top-level context
+line before matched results to visually group related output.
+This is useful when searching across deeply nested files, structured
+documents, logs, or hierarchical data where extra context improves
+readability and navigation"
+    }
+    fn update(
+        &self,
+        value: FlagValue,
+        args: &mut crate::flags::lowargs::LowArgs,
+    ) -> anyhow::Result<()> {
+        args.hierarchy = Some(value.unwrap_switch());
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+#[test]
+fn test_hierarchy() {
+    let args = parse_low_raw(None::<&str>).unwrap();
+    assert_eq!(None, args.hierarchy);
+
+    let args = parse_low_raw(["--hierarchy"]).unwrap();
+    assert_eq!(Some(true), args.hierarchy);
+
+    let args = parse_low_raw(["--no-hierarchy"]).unwrap();
+    assert_eq!(Some(false), args.hierarchy);
+
+    let args = parse_low_raw(["--hierarchy", "--no-hierarchy"]).unwrap();
+    assert_eq!(Some(false), args.hierarchy);
+
+    let args = parse_low_raw(["--no-hierarchy", "--hierarchy"]).unwrap();
+    assert_eq!(Some(true), args.hierarchy);
+}
+
 /// --hostname-bin
 #[derive(Debug)]
 struct HostnameBin;

crates/core/flags/hiargs.rs

@@ -57,6 +57,8 @@ pub(crate) struct HiArgs {
     globs: ignore::overrides::Override,
     heading: bool,
     hidden: bool,
+    /// Whether to print hierarchical parent lines for each match.
+    hierarchy: bool,
     hyperlink_config: grep::printer::HyperlinkConfig,
     ignore_file_case_insensitive: bool,
     ignore_file: Vec<PathBuf>,
@@ -163,6 +165,7 @@ impl HiArgs {
             Some(false) => false,
             Some(true) => !low.vimgrep,
         };
+        let hierarchy = low.hierarchy.unwrap_or(false);
         let path_terminator = if low.null { Some(b'\x00') } else { None };
         let quit_after_match = stats.is_none() && low.quiet;
         let threads = if low.sort.is_some() || paths.is_one_file {
@@ -274,6 +277,7 @@ impl HiArgs {
             follow: low.follow,
             heading,
             hidden: low.hidden,
+            hierarchy,
             hyperlink_config,
             ignore_file: low.ignore_file,
             ignore_file_case_insensitive: low.ignore_file_case_insensitive,
@@ -360,6 +364,12 @@ impl HiArgs {
         builder
     }
 
+    /// Whether to print hierarchical parent lines for each match.
+    #[allow(dead_code)]
+    pub(crate) fn hierarchy(&self) -> bool {
+        self.hierarchy
+    }
+
     /// Return the matcher that should be used for searching using the engine
     /// choice made by the user.
     ///
@@ -703,7 +713,8 @@ impl HiArgs {
             .preprocessor_globs(self.pre_globs.clone())
             .search_zip(self.search_zip)
             .binary_detection_explicit(self.binary.explicit.clone())
-            .binary_detection_implicit(self.binary.implicit.clone());
+            .binary_detection_implicit(self.binary.implicit.clone())
+            .hierarchy(self.hierarchy);
         Ok(builder.build(matcher, searcher, printer))
     }
 

crates/core/flags/lowargs.rs

@@ -59,6 +59,7 @@ pub(crate) struct LowArgs {
     pub(crate) globs: Vec<String>,
     pub(crate) heading: Option<bool>,
     pub(crate) hidden: bool,
+    pub(crate) hierarchy: Option<bool>,
     pub(crate) hostname_bin: Option<PathBuf>,
     pub(crate) hyperlink_format: HyperlinkFormat,
     pub(crate) iglobs: Vec<String>,