CLI Entry and Flag Parsing

This code turns process arguments and optional configuration-file arguments into the runtime settings used by ripgrep. The path begins at main, continues through parsing and argument resolution, and ends when the selected execution mode starts.

It exists to keep token parsing separate from runtime setup: LowArgs stores parsed option state, while HiArgs holds resolved settings used by execution paths.

Sources: crates/core/main.rs:44-67, crates/core/flags/parse.rs:49-54, crates/core/main.rs:78-107, crates/core/flags/lowargs.rs:33-113, crates/core/flags/hiargs.rs:36-107

Core concepts

Entry point

The entry point is main, which invokes parsing, dispatches through run, and converts errors into process exit codes.

Sources: crates/core/main.rs:44-67

Parse result

ParseResult distinguishes successful arguments, special modes, and errors; and_then preserves special modes and errors without invoking the next conversion.

Sources: crates/core/flags/parse.rs:36-45

Flag definition

A Flag describes a flag’s names, aliases, negation, value shape, documentation, and update operation for LowArgs.

Sources: crates/core/flags/mod.rs:74-185

Low-level arguments

LowArgs is the mutable intermediate structure containing mode, positional inputs, patterns, and individual option values.

Sources: crates/core/flags/lowargs.rs:33-113

High-level arguments

HiArgs is the resolved configuration used by search, file listing, type listing, indexing, and generation paths.

Sources: crates/core/flags/hiargs.rs:36-107, crates/core/main.rs:78-107

The startup call path

This sequence shows how process startup reaches the first file-search hand-off visible in the supplied code.

main calls flags::parse, passes the result to run, and returns exit code 0 for broken pipes, 2 for other errors, or the code returned by run.

parse calls parse_low, then converts ordinary LowArgs with HiArgs::from_low_args; special modes and errors remain separate outcomes.

run dispatches by args.mode(). Search can be skipped when matches are impossible, read from an index, run serially, or run in parallel; other branches write an index, list files, list types, or generate output.

For the ordinary search path, search builds haystacks from traversal results, orders them, creates a search worker, and invokes searcher.search(&haystack) for each haystack. The supplied excerpts stop at that search call; they do not show the searcher’s internal first byte read.

Sources: crates/core/main.rs:44-67, crates/core/flags/parse.rs:49-54, crates/core/flags/parse.rs:36-45, crates/core/main.rs:78-99, crates/core/main.rs:113-157

How raw arguments become LowArgs

This architecture view separates the parser registry, intermediate state, resolution step, and execution dispatch.

FLAGS is the static registry of flag implementations. The Flag contract distinguishes switches from value-taking flags with is_switch, exposes long names and optional short names, and defines update to mutate LowArgs.

The parser chooses these forms from the matched flag metadata, then calls update with the resulting value.

Parser::new builds lookup information once from FLAGS, recording each long name, alias, short name, and negated name before constructing FlagMap. Parser::parse lexes raw arguments, stores positional values, resolves short and long names, reports unknown flags, and updates the supplied LowArgs.

parse_low_raw exposes the same low-level operation for an arbitrary iterator: it creates default LowArgs, creates a Parser, parses the iterator, and returns the populated state.

Sources: crates/core/flags/defs.rs:44-156, crates/core/flags/mod.rs:74-185, crates/core/flags/parse.rs:273-287, crates/core/flags/parse.rs:176-216, crates/core/flags/parse.rs:221-290, crates/core/flags/parse.rs:139-145

How configuration arguments merge with CLI arguments

The dataflow below shows the configuration-file path and the final parse.

config::args reads RIPGREP_CONFIG_PATH; an absent or empty variable produces no arguments, while a configured path is opened and parsed. The reader ignores trimmed blank lines and comments, converts other lines into OsString arguments, and records conversion errors with line numbers.

parse_low first parses command-line arguments, sets logging levels, returns immediately for special modes, and honors --no-config. When configuration arguments are present, it places them in final_args, appends std::env::args_os().skip(1), and parses that combined iterator into a fresh LowArgs.

Sources: crates/core/flags/config.rs:16-39, crates/core/flags/config.rs:84-108, crates/core/flags/parse.rs:64-91, crates/core/flags/parse.rs:92-112

How LowArgs becomes runtime configuration

HiArgs::from_low_args validates sorting, rejects unsupported indexing combinations, normalizes related search modes, creates conversion state, and derives patterns, paths, types, globs, color behavior, output settings, and thread count. The resulting structure stores resolved paths, patterns, mode, types, globs, memory-map choice, sorting, output choices, and thread count.

Later HiArgs methods construct the runtime components. matcher selects the Rust matcher, PCRE2 matcher, or automatic fallback. searcher configures line termination, limits, inversion, multiline behavior, memory mapping, context, and encoding. search_worker combines the matcher, searcher, printer, preprocessing, archive handling, and binary detection.

walk_builder applies paths, ignore files, depth, links, size, threads, overrides, types, hidden-file behavior, Git-ignore behavior, and the current directory. During search, traversal results become haystacks, sorting determines their order, and the search worker processes each one.

Sources: crates/core/flags/hiargs.rs:114-185, crates/core/flags/hiargs.rs:36-107, crates/core/flags/hiargs.rs:379-413, crates/core/flags/hiargs.rs:722-759, crates/core/flags/hiargs.rs:705-719, crates/core/flags/hiargs.rs:885-928, crates/core/main.rs:113-157

How it connects

Resolved HiArgs hand off to traversal and search-worker machinery described in Search Worker and I/O and Parallel Directory Traversal.

Matcher construction connects to The Matcher Trait and Internal Iteration, The Default Rust Regex Matcher, and The PCRE2 Matcher.

Walker configuration connects to Gitignore and Override Matching and The Globset Matching Engine. Printer selection connects to Output Printers.

Sources: crates/core/flags/hiargs.rs:379-413

Key takeaways

• main parses arguments, dispatches through run, and handles exit codes.
• LowArgs stores parsed intermediate state; HiArgs::from_low_args resolves runtime configuration.
• Configuration arguments are loaded when enabled and combined with command-line arguments before parsing.
• run selects search, indexed search, file listing, type listing, generation, or other modes.
• A normal search creates traversal and search components before calling searcher.search(&haystack).