Skip to content

Command Reference

Jump to bottom
Mikhail Deynekin edited this page Dec 23, 2025 · 6 revisions

Command Reference

Complete and detailed command reference for sr-search-replace, covering all available options, flags, and their usage with practical examples.

Quick Command Reference

Command Purpose Example Details
-d, --debug Enable detailed debug output sr -d "pattern" "replacement" file.txt Basic Syntax
-nr, --no-recursive Process current directory only sr "pattern" "replacement" --no-recursive . Basic Syntax
-b, --binary Allow binary file processing sr "pattern" "replacement" --binary file.bin Binary Support
-f, -s, --find-opts="FLAGS" Custom grep options sr "pattern" "replacement" --find-opts="-i" file.txt Tool-Specific
-i Case-insensitive search sr -i "Pattern" "replacement" file.txt Search & Replace
-w, --word-boundary Match whole words only sr -w "word" "newword" file.txt Search & Replace
-e, --extended-regex Use extended regex syntax sr -e "(pattern1|pattern2)" "replacement" file.txt Search & Replace
-m, --multiline Multiline regex matching sr -m "line1.*line2" "replacement" file.txt Search & Replace
-l, --line-numbers Show line numbers in output sr -l "pattern" "replacement" --dry-run file.txt Debugging
--dot-all Dot matches newlines sr --dot-all ".+" "replacement" file.txt Debugging
-no-global Replace only first occurrence sr -no-global "pattern" "replacement" file.txt Tool-Specific
-find-opts="FLAGS" Custom find options sr "pattern" "replacement" -find-opts="--depth=2" . Tool-Specific
-sed-opts="FLAGS" Custom sed options sr "pattern" "replacement" -sed-opts="-e" file.txt Tool-Specific
--grep-opts="FLAGS" Custom grep options sr "pattern" "replacement" --grep-opts="-P" file.txt Tool-Specific
-nb, -no-backup Skip backup creation sr "pattern" "replacement" -nb --recursive . Backup Control
-fb, -force-backup Create backups always sr "pattern" "replacement" -fb file.txt Backup Control
-nbf, --no-backup-folder No backup directory creation sr "pattern" "replacement" -nbf file.txt Backup Control
-md, --max-depth NUM Limit recursion depth sr "pattern" "replacement" -md 2 --recursive . Advanced Options
-c, --max-size MB File size limit sr "pattern" "replacement" -c 50 --recursive . Advanced Options
-dry-run, -d Preview changes without modifying sr "pattern" "replacement" --dry-run --recursive . Usage Examples
--preserve-ownership Keep original file ownership sr "pattern" "replacement" --preserve-ownership file.txt Advanced Options
-dslm, --delimiter CHAR Custom sed delimiter sr "pattern:replacement" -dslm ':' file.txt Advanced Options
-Encoding ENC File encoding mode sr "pattern" "replacement" -Encoding ENC file.txt Advanced Options
-xL, --exclude-hidden Skip hidden files/dirs sr "pattern" "replacement" -xL --recursive . Advanced Options
-xB, --exclude-binary Skip binary files sr "pattern" "replacement" -xB --recursive . Advanced Options
-xs, --max-size MB Maximum file size sr "pattern" "replacement" -xs 100 --recursive . Advanced Options
-xp, --exclude-patterns PATTERN Exclude files by pattern sr "pattern" "replacement" -xp "*.log" --recursive . Advanced Options
-xd, --exclude-dirs DIRS Exclude directories sr "pattern" "replacement" -xd "node_modules,dist" --recursive . Advanced Options
-h, --help Show help message sr --help Information & Help
-v, --version Show version sr --version Information & Help

Option Combinations Guide

Category Options Use Case Example
Safe Production -dry-run, -force-backup, -verbose, -recursive, -exclude-dirs=".git" Preview first, ensure backup, see all files Safe Production Replacement
Performance -skip-binary, -max-size=50, -exclude-hidden, -no-recursive, -no-backup Current dir only, binary files skipped, fast Performance-Optimized
Debugging -debug, -line-numbers, -context=5, -dry-run, -extended-regex Full debug output, show context Debugging Complex Patterns

Table of Contents

Basic Syntax

The fundamental structure of sr-search-replace commands:

sr [OPTIONS] PATTERN [REPLACEMENT] [FILE|DIR]

where:

  • [OPTIONS] - Must come before positional arguments
  • PATTERN - Regex pattern to find
  • [REPLACEMENT] - Text to replace with (optional, if not provided only counts finds)
  • [FILE|DIR] - Target file or directory (optional, defaults to current directory)

Core Functionality Options

-d, --debug

Enable detailed debug output for troubleshooting.

Usage:

sr -d "pattern" "replacement" file.txt
sr --debug "pattern" "replacement" file.txt

Features:

  • Shows detailed operation trace
  • Displays internal processing steps
  • Useful for pattern matching issues
  • More verbose than --verbose

Example Output:

[DEBUG] Scanning directory: /src
[DEBUG] Found file: app.js
[DEBUG] Pattern matches: 5 occurrences
[DEBUG] Replacement app.js[0] -> app.js
[DEBUG] Session metadata finalized

-nr, --no-recursive

Process only the current directory without recurring into subdirectories.

Usage:

sr "pattern" "replacement" --no-recursive .
sr "pattern" "replacement" -nr .

Behavior:

  • Files only in the specified directory are processed
  • Subdirectories completely ignored
  • Useful for limiting scope of replacements

Example:

# Process only files in current dir, skip subdirs
sr "OldClass" "NewClass" -nr .

Search & Replace Enhancements

-i (case-insensitive)

Perform case-insensitive pattern matching.

Usage:

sr -i "pattern" "replacement" file.txt

Example:

sr -i "OLD" "new" file.txt  # Matches "old", "OLD", "Old"

-w, --word-boundary

Match pattern only at word boundaries.

Usage:

sr -w "word" "newword" file.txt

Example:

sr -w "class" "klass" app.js  # Matches "class" but not "class_name"

-e, --extended-regex

Use extended regex syntax (ERE) for pattern matching.

Usage:

sr -e "(pattern1|pattern2)" "replacement" file.txt

-m, --multiline

Enable multiline regex matching where . matches across lines.

Usage:

sr -m "pattern" "replacement" file.txt

-l, --line-numbers

Show line numbers where matches occur.

Usage:

sr -l "pattern" "replacement" --dry-run file.txt

Tool-Specific Options

-b, --binary

Allow processing of binary files (use with caution).

Usage:

sr "pattern" "replacement" --binary file.bin

-f, -s, --find-opts="FLAGS"

Pass custom flags directly to the find command.

Usage:

sr "pattern" "replacement" --find-opts="--depth=2" .

-sed-opts="FLAGS"

Pass custom flags to sed.

Usage:

sr "pattern" "replacement" -sed-opts="-e" file.txt

--grep-opts="FLAGS"

Pass custom flags to grep.

Usage:

sr "pattern" "replacement" --grep-opts="-P" file.txt

Backup Control Options

-nb, -no-backup

Skip creating backups before replacement.

Usage:

sr "pattern" "replacement" -nb file.txt
sr "pattern" "replacement" --no-backup file.txt

Warning: Use with caution - no backup means no undo capability!

-fb, -force-backup

Always create backups, even if typically skipped.

Usage:

sr "pattern" "replacement" -fb file.txt
sr "pattern" "replacement" --force-backup file.txt

-nbf, --no-backup-folder

Do not create backup directory structure.

Usage:

sr "pattern" "replacement" -nbf file.txt

Safety Features

  • Binary Detection: Multi-layer system prevents accidental binary corruption
  • Backup Creation: Automatic backups before any modification
  • Dry-Run Mode: Preview changes without writing
  • Session Tracking: Complete rollback capability via session metadata

Advanced Options

-md, --max-depth NUM

Limit recursion depth when searching directories.

Usage:

sr "pattern" "replacement" -md 2 --recursive .

-c, --max-size MB

Skip files larger than specified size.

Usage:

sr "pattern" "replacement" -c 50 --recursive .  # Skip files > 50MB

--preserve-ownership

Maintain original file ownership and permissions.

Usage:

sr "pattern" "replacement" --preserve-ownership file.txt

-dslm, --delimiter CHAR

Use custom delimiter for sed operations.

Usage:

sr "pattern:replacement" -dslm ':' file.txt

-xL, --exclude-hidden

Skip hidden files and directories.

Usage:

sr "pattern" "replacement" -xL --recursive .

-xB, --exclude-binary

Skip binary files.

Usage:

sr "pattern" "replacement" -xB --recursive .

-xs, --max-size MB

Maximum file size to process.

Usage:

sr "pattern" "replacement" -xs 100 --recursive .

-xp, --exclude-patterns PATTERN

Exclude files matching patterns.

Usage:

sr "pattern" "replacement" -xp "*.log,*.tmp" --recursive .

-xd, --exclude-dirs DIRS

Exclude specific directories.

Usage:

sr "pattern" "replacement" -xd "node_modules,.git,dist" --recursive .

Information & Help

-h, --help

Display help message with all available options.

Usage:

sr --help
sr -h

-v, --version

Show version information.

Usage:

sr --version
sr -v

Output example:

sr-search-replace version 6.1.0
Build: 2025-02-23
License: MIT

Usage Examples

Example 1: Safe Refactoring

# 1. Preview changes
sr --dry-run "OldClass" "NewClass" --recursive src/

# 2. Check with context
sr --dry-run "OldClass" "NewClass" --recursive src/ -c 3

# 3. Apply with backup
sr "OldClass" "NewClass" --backup --recursive src/

Example 2: Complex Pattern Replacement

# Replace function calls with extended regex
sr -e "([a-zA-Z_][a-zA-Z0-9_]*)\\(" "${1}_new(" --dry-run file.js

Example 3: Config File Updates

# Find and replace with custom delimiter
sr "old/path/to/config" "new/path/to/config" \\
--exclude-patterns="*.bak *.tmp" \\
--backup --recursive .

Example 4: Binary-Safe Processing

sr "pattern" "replacement" \\
--skip-binary \\
--exclude-dirs=".git,node_modules" \\
--max-size=100 \\
--recursive .

Example 5: Encoding-Aware Replacement

sr "text" "replacement" \\
--encoding=iso-8859-1 \\
--backup \\
legacy_file.txt

Option Combinations

Safe Production Replacement

sr "OLD" "NEW" \\
--dry-run \\
--force-backup \\
--verbose \\
--recursive \\
--exclude-dirs=".git,.svn" \\
--exclude-patterns="*.bak" \\
--preserve-ownership \\
.

Performance-Optimized

sr "pattern" "replacement" \\
--skip-binary \\
--max-size=50 \\
--exclude-hidden \\
--no-recursive \\
--no-backup \\
.

Debugging Complex Patterns

sr "pattern" "replacement" \\
--debug \\
--line-numbers \\
--context=5 \\
--dry-run \\
--extended-regex \\
file.txt

See Also

Clone this wiki locally