Struct TraverseOptions 

pub struct TraverseOptions {
    pub case_sensitive: bool,
    pub respect_gitignore: bool,
    pub only_text_files: bool,
    pub pattern: Option<String>,
    pub depth: Option<usize>,
    pub omit_path_prefix: Option<PathBuf>,
}

Configuration options for directory traversal operations.

Controls the behavior of the traversal functionality, including case sensitivity, gitignore handling, file type filtering, and pattern matching.

Examples

use lumin::traverse::TraverseOptions;
use std::path::PathBuf;

// Default options: case-insensitive, respect gitignore, only text files, no pattern
let default_options = TraverseOptions::default();

// Case-sensitive, include binary files, with a glob pattern
let custom_options = TraverseOptions {
    case_sensitive: true,
    respect_gitignore: true,
    only_text_files: false,
    pattern: Some("**/*.{rs,toml}".to_string()),
    depth: Some(10),
    omit_path_prefix: None,
};

// Case-insensitive, include all files, with a substring pattern
let search_options = TraverseOptions {
    case_sensitive: false,
    respect_gitignore: false,
    only_text_files: false,
    pattern: Some("config".to_string()),
    depth: None,
    omit_path_prefix: None,
};

// With path prefix removal to show relative paths
let prefix_options = TraverseOptions {
    case_sensitive: false,
    respect_gitignore: true,
    only_text_files: true,
    pattern: None,
    depth: Some(20),
    omit_path_prefix: Some(PathBuf::from("/home/user/projects/myrepo")),
};

Fields

case_sensitive: bool

Whether file path matching should be case sensitive.

When true, file paths must exactly match the case in the pattern. When false (default), file paths will match regardless of case.

Examples

• With case_sensitive: true, pattern “Config” will match “Config.txt” but not “config.txt”
• With case_sensitive: false, pattern “config” will match both “config.txt” and “Config.txt”

respect_gitignore: bool

Whether to respect .gitignore files when determining which files to include.

When true (default), files and directories listed in .gitignore will be excluded. When false, all files will be included, even those that would normally be ignored.

Examples

• With respect_gitignore: true, files like .git/, node_modules/, tmp files, or patterns specified in .gitignore will be excluded
• With respect_gitignore: false, all files will be included regardless of their presence in .gitignore files

only_text_files: bool

Whether to only return text files (filtering out binary files).

When true (default), binary files like images, executables, etc. will be excluded. When false, all files will be included regardless of their content type.

Examples

• With only_text_files: true, files like .txt, .md, .rs will be included, but .jpg, .png, executables will be excluded
• With only_text_files: false, all files will be included regardless of their type

pattern: Option<String>

Optional pattern to filter files by path.

Supports two types of patterns:

• Glob patterns (e.g., “.rs”, “**/.txt”) with special characters like *, ?, [], etc.
• Simple substring patterns (e.g., “README”, “config”) for searching within file paths

Path Matching Behavior

Important: Glob patterns are matched against paths that are relative to the traversal directory. This ensures consistent behavior across the codebase and makes patterns predictable.

For example, when traversing /home/user/project:

• A file at /home/user/project/src/main.rs is matched against the relative path src/main.rs
• A file at /home/user/project/docs/readme.md is matched against the relative path docs/readme.md

The pattern type is automatically detected based on glob special characters. Pattern matching respects the case_sensitive setting.

Consistency with Search Module

This parameter works consistently with include_glob and exclude_glob in the search module - all use relative paths for pattern matching. This unified approach allows you to use the same pattern format across different parts of the library.

Glob Pattern Examples

Basic Wildcards

• *.txt - All files with .txt extension in the current directory
• **/*.txt - All .txt files in any subdirectory (recursive)
• file?.txt - Matches file1.txt or fileA.txt, but not file10.txt (? matches one character)
• src/*.rs - All Rust files in the src directory
• **/test_*.rs - All Rust files starting with “test_” in any directory
• doc*.pdf - All PDF files starting with “doc” in the current directory
• */**/backup_* - All files starting with “backup_” in any subdirectory at least one level deep
• logs/*.log - All log files in the logs directory
• **/*2023* - All files containing “2023” in their name in any directory
• *_test.js - All JavaScript files ending with “_test” in the current directory

Prefix Matching

• prefix_* - Matches all files starting with “prefix_” in the current directory only
• **/prefix_* - Matches all files starting with “prefix_” in any directory
• src/module_* - Matches files starting with “module_” in the src directory
• config_*.{json,yaml} - Matches config files with specific prefix and extensions
• lib_*.rs - All Rust files starting with “lib_” in the current directory
• **/api_v*.js - All JavaScript files starting with “api_v” in any directory
• **/model_*.{py,rs,js} - Files starting with “model_” with specified extensions
• src/**/util_* - Files starting with “util_” in any subdirectory of src
• test_*.{rs,go} - Test files in the current directory with specific extensions
• doc_draft_*.md - Markdown files starting with “doc_draft_” in the current directory

Character Classes

• file[123].txt - Matches file1.txt, file2.txt, and file3.txt only
• [a-z]*.rs - Rust files starting with a lowercase letter
• data/[0-9]?_*.dat - Data files with specific naming pattern
• **/level[a-zA-Z0-9].txt - Files named level followed by any letter or digit
• **/[!0-9]*.txt - Files not starting with a digit
• report[A-D]_*.pdf - PDF files starting with reportA_, reportB_, reportC_, or reportD_
• temp[_-]*.log - Log files starting with temp_ or temp-
• **/[a-f][0-9]*.json - JSON files starting with a-f followed by a digit
• **/*[!.][!.][!.] - Files with exactly 3-character names, no dots
• data/202[0-3]* - Files in data/ starting with years 2020-2023

Brace Expansion

• *.{txt,md,rs} - Files with .txt, .md, or .rs extensions
• **/{test,spec}/*.js - All JS files in any “test” or “spec” directory
• {src,lib}/**/*.rs - Rust files in src or lib directories or their subdirectories
• **/{configs,settings}/*.{json,yml} - Configuration files with specific extensions
• {api,service,util}/*.{js,ts} - JavaScript/TypeScript files in specific directories
• docs/{*.md,*.txt,README*} - Documentation files with specific patterns
• **/build/{debug,release}/*.{exe,dll} - Binary files in debug or release directories
• {2021,2022,2023}/{jan,feb,mar}/*.csv - CSV files organized by year and month
• **/{styles,css,themes}/*.{css,scss} - Style-related files in specific directories
• {bin,scripts}/{*.sh,*.bash,*.zsh} - Shell scripts in specific directories

Suffix Matching

• *.{rs,toml} - Files with .rs or .toml extensions in the current directory
• **/*_test.rs - All Rust files ending with “_test” in any directory
• **/auth*.{js,ts} - Files containing “auth” in any directory
• *_backup.* - Files ending with “_backup” with any extension
• **/*-v1.{json,yaml} - Config files ending with “-v1” with specific extensions
• **/*_controller.{js,ts} - Controller files with JS or TS extensions
• **/*_spec.{rb,py} - Spec files in Ruby or Python
• **/*_example.* - Any file ending with “_example” with any extension
• **/*demo.* - Any file ending with “demo” with any extension
• **/*FINAL* - Files with “FINAL” in their name (case-sensitive if enabled)

Complex Patterns

• **/nested/**/*[0-9].{txt,md} - Files ending with a digit in any nested directory
• **/{test,spec}_[a-z]*/*.{js,ts} - Test files with specific naming patterns
• **/[a-z]*-[0-9].{txt,md,json} - Files with specific name pattern (lowercase-digit.ext)
• **/{docs,images}/[!.]* - Non-hidden files in docs or images directories
• **/*_{test,spec}/**/[a-z]*_test.{js,ts} - Complex test file organization
• **/{bin,lib}/{debug,release}/**/*[0-9].{so,dll,dylib} - Binary libraries with version numbers
• src/**/{model,schema}/*[A-Z]*.{rs,go} - Model files starting with uppercase in specific directories
• **/{v1,v2,v3}/**/{public,private}/*.{js,ts} - API version-specific files
• **/*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]* - Files containing dates (YYYY-MM-DD)
• **/test*/**/{unit,integration}/**/*.{test,spec}.* - Structured test files

Substring Pattern Examples

When a pattern doesn’t contain glob special characters, it’s treated as a simple substring match:

• config - Any file with “config” in its path (e.g., “config.toml”, “app_config.json”)
• test - Any file with “test” in its path (e.g., “test_data.txt”, “tests/example.rs”)
• README - Any file with “README” in its path, case-sensitive if enabled
• util - Any file with “util” in its path (e.g., “utils.rs”, “utility.js”)
• controller - Any file with “controller” in its path
• model - Any file with “model” in its path (e.g., “user_model.rs”, “models/item.js”)
• api - Any file with “api” in its path (paths, filenames, extensions)
• 2023 - Any file with “2023” in its path (useful for date-based searches)
• v1 - Any file with “v1” in its path (useful for versioned files)
• backup - Any file with “backup” in its path

depth: Option<usize>

Maximum depth of directory traversal (number of directory levels to explore).

When Some(depth), the traversal will only explore up to the specified number of directory levels. When None, the traversal will explore directories to their full depth. Default is Some(20) to prevent excessive traversal of deeply nested directories.

Examples

• With depth: Some(1), only files in the immediate directory will be included (no subdirectories)
• With depth: Some(2), files in the immediate directory and one level of subdirectories will be included
• With depth: Some(5), the traversal will go up to 5 levels deep
• With depth: None, all subdirectories will be explored regardless of depth

omit_path_prefix: Option<PathBuf>

Optional path prefix to remove from file paths in traversal results.

When set to Some(path), this prefix will be removed from the beginning of each file path in the results. If a file path doesn’t start with this prefix, it will be left unchanged. When set to None (default), file paths are returned as-is.

This is useful when you want to display relative paths instead of full paths in results, or when you want to normalize paths for consistency.

Examples

• omit_path_prefix: Some(PathBuf::from("/home/user/projects/myrepo")) will transform a file path like /home/user/projects/myrepo/src/main.rs to src/main.rs in the results
• omit_path_prefix: None will leave all file paths unchanged

If a file path doesn’t start with the specified prefix, it will remain unchanged. For example, with the prefix /home/user/projects/myrepo, a file path like /var/log/syslog would remain /var/log/syslog in the results.

Trait Implementations

impl Clone for TraverseOptions

fn clone(&self) -> TraverseOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TraverseOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TraverseOptions

fn default() -> Self

Returns the “default value” for a type.