# How to Search for Patterns That Span Multiple Lines in ripgrep > Learn how to search for patterns that span multiple lines in ripgrep using the -U or --multiline flag. Master advanced regex matching across newlines efficiently. - Repository: [Andrew Gallant/ripgrep](https://github.com/BurntSushi/ripgrep) - Tags: how-to-guide - Published: 2026-03-05 --- **To search for patterns that span multiple lines in ripgrep, enable multiline mode with the `-U` or `--multiline` flag, which allows the regex engine to match across newline characters.** Ripgrep processes files line-by-line by default, preventing regular expressions from crossing line boundaries. This guide explains how to configure the BurntSushi/ripgrep tool to match patterns that extend across multiple lines using the core flags defined in the source code. ## Enabling Multiline Mode with the `-U` Flag By default, ripgrep restricts matches to single lines, which means a match cannot contain a newline character. To lift this restriction, use the `-U` (or `--multiline`) flag, which permits patterns to match across line terminators. According to the source code in [`crates/core/flags/defs.rs`](https://github.com/BurntSushi/ripgrep/blob/main/crates/core/flags/defs.rs), the `-U/--multiline` option "enables searching across multiple lines" by treating the input as a single continuous string rather than discrete lines. When this flag is active, a pattern such as `foo\nbar` will successfully match the literal two-line sequence where `foo` appears on one line and `bar` appears on the next. ### Dot-All Mode and the Dot Metacharacter Even with multiline mode enabled, the dot (`.`) metacharacter does **not** match newline characters by default. To allow `.` to span across lines, you must enable dot-all mode using the `--multiline-dotall` flag or embed the `(?s)` directive directly in your regex pattern. The user guide in [`GUIDE.md`](https://github.com/BurntSushi/ripgrep/blob/main/GUIDE.md) documents this interaction, noting that multiline mode handles the line-crossing behavior while dot-all mode controls whether the dot metacharacter matches newlines. ## Performance Implications of Multiline Searching Multiline mode fundamentally changes how ripgrep processes files, forcing the tool to read the entire file into memory (or fully memory-map it) before executing the search. This behavior increases memory consumption and may reduce search speed when processing very large files, as the engine can no longer stream through content line-by-line. ## Practical Command-Line Examples The test suite in [`tests/multiline.rs`](https://github.com/BurntSushi/ripgrep/blob/main/tests/multiline.rs) validates several common multiline use cases. Here are practical examples based on the implementation: Match a literal two-line sequence: ```bash rg -U 'abc\ndef' path/to/file ``` Allow `.` to match newlines for flexible pattern matching: ```bash rg -U --multiline-dotall 'of this world.+detective work' sherlock.txt ``` Extract only the matched text without printing entire lines: ```bash rg -U --only-matching 'Watson|Sherlock\p{Any}+?Holmes' file.txt ``` Generate Vim-compatible output for multiline matches: ```bash rg -U --vimgrep 'Watson|Sherlock\p{Any}+?Holmes' file.txt ``` ## Summary - **Use `-U` or `--multiline`** to enable patterns that match across line breaks in ripgrep, lifting the default restriction against newline characters in matches - **Combine with `--multiline-dotall`** or the embedded `(?s)` flag to allow the `.` metacharacter to match newline characters when spanning lines - **Expect higher memory usage** because multiline mode requires loading entire files into memory rather than streaming line-by-line - **Consult the implementation** in [`crates/core/flags/defs.rs`](https://github.com/BurntSushi/ripgrep/blob/main/crates/core/flags/defs.rs) and test cases in [`tests/multiline.rs`](https://github.com/BurntSushi/ripgrep/blob/main/tests/multiline.rs) for advanced usage patterns and edge cases ## Frequently Asked Questions ### Why doesn't my pattern match across lines even with the `-U` flag? The `-U` flag allows explicit newline characters (`\n`) in your pattern to match, but the dot (`.`) metacharacter still excludes newlines by default. If your pattern relies on `.` to span lines, you must add the `--multiline-dotall` flag or include `(?s)` at the start of your regex to enable dot-all mode according to the flag definitions in [`crates/core/flags/defs.rs`](https://github.com/BurntSushi/ripgrep/blob/main/crates/core/flags/defs.rs). ### How does multiline mode affect ripgrep's performance? Multiline mode prevents ripgrep from using its default streaming architecture. Instead of processing files line-by-line, the tool must load the entire file content into memory (or memory-map the whole file) before searching, which increases RAM usage and may slow down searches on very large files. ### Can I use multiline mode with ripgrep's replacement functionality? Yes, multiline mode works with replacement operations, allowing you to replace patterns that span multiple lines. Ensure you use the `-U` flag along with the replacement flag `-r` (or `--replace`), and remember that capture groups can reference text across line boundaries when multiline mode is active. ### Where are the multiline search options defined in the ripgrep source code? The command-line flags are defined in [`crates/core/flags/defs.rs`](https://github.com/BurntSushi/ripgrep/blob/main/crates/core/flags/defs.rs), which contains the documentation and implementation for both `--multiline` and `--multiline-dotall`. Comprehensive test cases demonstrating expected behavior are located in [`tests/multiline.rs`](https://github.com/BurntSushi/ripgrep/blob/main/tests/multiline.rs), while user-facing documentation appears in [`GUIDE.md`](https://github.com/BurntSushi/ripgrep/blob/main/GUIDE.md).