Skip to content

Tool Configuration

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

Tool Configuration

Comprehensive guide to configuring sr-search-replace through configuration files and direct code modification. All default parameters are defined in the Bash/Shell implementation.

Table of Contents

Configuration via Config File

sr-search-replace supports JSON-based configuration files for easy customization without modifying the script code. Configuration files allow you to set default values for all common options.

Config File Location

The script looks for configuration files in the following locations (in order):

  1. ~/.sr-search-replace/config.json (User config)
  2. /etc/sr-search-replace/config.json (System-wide config)
  3. ./.sr-config.json (Project-specific config)

Config File Format

Example ~/.sr-search-replace/config.json:

{
  "enableBackup": true,
  "backupDir": "~/.sr-backups",
  "skipBinary": true,
  "logLevel": "INFO",
  "timeout": 300,
  "maxRetries": 3,
  "excludePatterns": [".git", "node_modules", "*.bak"],
  "debugMode": false
}

Supported Config Parameters

The following JSON parameters can be set in the config file:

Parameter Type Default Description
enableBackup boolean true Create backups before replacements
backupDir string ~/.sr-backups Backup directory location
skipBinary boolean true Skip binary files during processing
logLevel string "INFO" Log level (DEBUG, INFO, WARNING, ERROR)
timeout number 300 Operation timeout in seconds
maxRetries number 3 Maximum number of retry attempts
excludePatterns array [".git"] File patterns to exclude
excludeDirs array ["node_modules"] Directories to exclude
debugMode boolean false Enable debug output
recursiveMode boolean true Enable recursive directory processing
preserveOwnership boolean true Preserve file ownership/permissions
maxDepth number 100 Maximum recursion depth
maxFileSizeMB number 100 Maximum file size in MB to process
timestampFormat string "%Y%m%d_%H%M%S" Backup timestamp format
sedDelimiter string `" "`

How Config File Values are Applied

When the script starts:

  1. Script loads built-in defaults from code (see below)
  2. If config file exists, values from JSON override built-in defaults
  3. Command-line arguments override both config file and built-in defaults

Priority Order (highest to lowest):

Command-line args > Config file > Built-in defaults

Configuration via Direct Code Modification

For advanced users who need tight control over defaults, you can edit the sr.sh script directly. Configuration constants are defined in a dedicated section at the top of the script.

Default Behavior Settings

These readonly variables define fundamental behavior defaults:

readonly SESSION_VERSION="6.1.0"               # Script version
readonly DEFAULT_DEBUG_MODE=false               # Enable detailed debug output
readonly DEFAULT_RECURSIVE_MODE=true            # Process directories recursively
readonly DEFAULT_DRY_RUN=false                  # Preview mode (no actual changes)
readonly DEFAULT_CREATE_BACKUPS=true            # Automatically create backups
readonly DEFAULT_BACKUP_IN_FOLDER=true          # Organize backups in folders
readonly DEFAULT_FORCE_BACKUP=false             # Always backup, even if skipped
readonly DEFAULT_PRESERVE_OWNERSHIP=true        # Keep file owner/permissions
readonly DEFAULT_MAX_DEPTH=100                  # Max directory recursion depth
readonly DEFAULT_TIMESTAMP_FORMAT="%Y%m%d_%H%M%S"  # Backup timestamp format
readonly DEFAULT_BACKUP_PREFIX="sr.backup"     # Backup file/folder prefix
readonly DEFAULT_TEMP_DIR="/tmp"              # Temporary directory location
readonly DEFAULT_SED_DELIMITER="|"             # Separator for sed s command
readonly DEFAULT_SKIP_HIDDEN_FILES=false        # Skip files starting with dot
readonly DEFAULT_SKIP_BINARY_FILES=true         # Skip binary files
readonly DEFAULT_MAX_FILE_SIZE_MB=100           # Max file size to process (MB)
readonly DEFAULT_ENCODING="UTF-8"              # Default file encoding
readonly DEFAULT_SEARCH_DIR="."                # Default search directory
readonly DEFAULT_REPLACE_MODE="inplace"        # inplace, copy, or backup_only

Key Defaults Explained:

  • DEBUG_MODE: When false, minimal output shown. Set to true for troubleshooting
  • RECURSIVE_MODE: When true, processes all subdirectories. Set to false to limit to current dir only
  • DRY_RUN: Essential for safety - preview changes before actual modification
  • CREATE_BACKUPS: Highly recommended to keep as true for safety
  • MAX_DEPTH: Controls recursion limit (100 = no practical limit for most systems)
  • SKIP_BINARY_FILES: Prevents accidental corruption of binary files
  • MAX_FILE_SIZE_MB: Prevents memory issues with huge files

Example Modification:

# To increase max file size from 100MB to 500MB
readonly DEFAULT_MAX_FILE_SIZE_MB=500

# To disable backups by default (NOT RECOMMENDED)
readonly DEFAULT_CREATE_BACKUPS=false

# To enable debug mode by default
readonly DEFAULT_DEBUG_MODE=true

Search/Replace Parameters

These control how pattern matching and replacement behaves:

readonly DEFAULT_IGNORE_CASE=false              # -i: Case-insensitive search
readonly DEFAULT_MULTILINE_MATCH=false          # -m: Multiline regex mode
readonly DEFAULT_EXTENDED_REGEX=false           # -e: Extended regex syntax
readonly DEFAULT_WORD_BOUNDARY=false            # -w: Match whole words only
readonly DEFAULT_LINE_NUMBERS=false             # -l: Show line numbers
readonly DEFAULT_DOT_ALL=false                  # Dot matches newlines
readonly DEFAULT_GLOBAL_REPLACE=true            # Replace all occurrences

Example Modifications:

# For case-insensitive by default
readonly DEFAULT_IGNORE_CASE=true

# For word boundary matching
readonly DEFAULT_WORD_BOUNDARY=true

# To disable global replace (only replace first match)
readonly DEFAULT_GLOBAL_REPLACE=false

Tool Configuration

Specifies which external tools to use and their default flags:

readonly FIND_TOOL="find"                      # File search utility
readonly SED_TOOL="sed"                         # Stream editor
readonly GREP_TOOL="grep"                       # Pattern search utility

readonly DEFAULT_FIND_FLAGS=""                 # Additional find flags
readonly DEFAULT_SED_FLAGS=""                  # Additional sed flags
readonly DEFAULT_GREP_FLAGS="-F"               # Default: Fixed string matching

Example Modifications:

# To use gsed (GNU sed) on macOS instead of BSD sed
readonly SED_TOOL="gsed"

# To add default find flags
readonly DEFAULT_FIND_FLAGS="-not -path '*/\\.*'"

# To enable perl regex in grep
readonly DEFAULT_GREP_FLAGS="-P"

Color Scheme Customization

Control output colors for different message types:

readonly COLOR_INFO='\033[0;34m'        # Blue - informational messages
readonly COLOR_SUCCESS='\033[0;32m'     # Green - successful operations
readonly COLOR_WARNING='\033[0;33m'     # Yellow - warnings
readonly COLOR_ERROR='\033[0;31m'       # Red - errors
readonly COLOR_DEBUG='\033[0;36m'       # Cyan - debug output
readonly COLOR_HEADER='\033[0;35m'      # Magenta - section headers
readonly COLOR_RESET='\033[0m'          # Reset to default

ANSI Color Codes Reference:

  • \033[0;30m - Black
  • \033[0;31m - Red
  • \033[0;32m - Green
  • \033[0;33m - Yellow
  • \033[0;34m - Blue
  • \033[0;35m - Magenta
  • \033[0;36m - Cyan
  • \033[0;37m - White

Example Modification:

# Disable colors (for CI/CD environments)
readonly COLOR_INFO=''
readonly COLOR_SUCCESS=''
readonly COLOR_WARNING=''
readonly COLOR_ERROR=''
readonly COLOR_DEBUG=''
readonly COLOR_HEADER=''

Exclusion Patterns

Define files and directories to automatically exclude from processing:

readonly DEFAULT_EXCLUDE_PATTERNS=".git .svn .hg .DS_Store *.bak *.backup"
readonly DEFAULT_EXCLUDE_DIRS="node_modules __pycache__ .cache .idea .vscode"

Explanation:

  • EXCLUDE_PATTERNS: Space-separated file patterns (glob-style wildcards)
  • EXCLUDE_DIRS: Space-separated directory names to skip entirely

Example Modifications:

# Add Terraform and Docker files
readonly DEFAULT_EXCLUDE_PATTERNS=".git .svn *.bak *.tfstate Dockerfile"

# Add build directories
readonly DEFAULT_EXCLUDE_DIRS="node_modules __pycache__ .cache dist build target"

# Minimal exclusions
readonly DEFAULT_EXCLUDE_PATTERNS=".git"
readonly DEFAULT_EXCLUDE_DIRS="node_modules"

Binary Detection Settings

Controls how the script detects and handles binary files:

readonly DEFAULT_BINARY_DETECTION_METHOD="multi_layer"  # multi_layer, file_only, grep_only
readonly DEFAULT_BINARY_CHECK_SIZE=1024                  # Bytes to check
readonly DEFAULT_ALLOW_BINARY=false                      # Require -b flag

Detection Methods:

  • multi_layer: Uses multiple techniques (grep, file command, byte checking)
  • file_only: Relies only on file command MIME type checking
  • grep_only: Uses only grep heuristics for detection

Example Modification:

# For faster processing (less accurate binary detection)
readonly DEFAULT_BINARY_DETECTION_METHOD="grep_only"

# Check more bytes for binary detection
readonly DEFAULT_BINARY_CHECK_SIZE=8192

# Allow binary processing without explicit flag (RISKY)
readonly DEFAULT_ALLOW_BINARY=true

Rollback Settings

Control backup retention and rollback functionality:

readonly DEFAULT_ROLLBACK_ENABLED=true          # Enable rollback feature
readonly DEFAULT_MAX_BACKUPS=10                 # Keep last N backup sets

Example Modifications:

# Disable automatic rollback
readonly DEFAULT_ROLLBACK_ENABLED=false

# Keep 30 backup versions
readonly DEFAULT_MAX_BACKUPS=30

Recommendations by Use Case

Production Environment

readonly DEFAULT_DEBUG_MODE=false               # No debug noise
readonly DEFAULT_DRY_RUN=false                  # Actual changes OK
readonly DEFAULT_CREATE_BACKUPS=true            # ALWAYS backup
readonly DEFAULT_FORCE_BACKUP=true              # Force backups
readonly DEFAULT_PRESERVE_OWNERSHIP=true        # Keep permissions
readonly DEFAULT_SKIP_BINARY_FILES=true         # Safety first
readonly DEFAULT_MAX_FILE_SIZE_MB=100           # Reasonable limit

Development Environment

readonly DEFAULT_DEBUG_MODE=true                # Debug info helpful
readonly DEFAULT_DRY_RUN=true                   # Preview by default
readonly DEFAULT_CREATE_BACKUPS=true            # Still backup
readonly DEFAULT_SKIP_HIDDEN_FILES=false        # Process dotfiles
readonly DEFAULT_SKIP_BINARY_FILES=true         # Still skip binary

High-Volume Processing

readonly DEFAULT_SKIP_BINARY_FILES=true         # Safety
readonly DEFAULT_BINARY_DETECTION_METHOD="grep_only"  # Faster
readonly DEFAULT_MAX_FILE_SIZE_MB=500           # Allow larger files
readonly DEFAULT_SKIP_HIDDEN_FILES=true         # Skip hidden
readonly DEFAULT_EXCLUDE_DIRS=".git .cache .idea" # Skip common dirs

DEFAULT_FIND_FLAGS - Custom Find Options

Additional command-line flags to pass to the find utility for file discovery.

Default Value: "" (empty string)

Purpose: Extend the default behavior of find command with custom options without modifying the core search logic.

Useful Find Flags:

Flag Description Example
-not -path '*/\.*' Exclude hidden paths readonly DEFAULT_FIND_FLAGS="-not -path '*/\\.*'"
-type f Find files only (not directories) readonly DEFAULT_FIND_FLAGS="-type f"
-type d Find directories only readonly DEFAULT_FIND_FLAGS="-type d"
-mtime -7 Modified in last 7 days readonly DEFAULT_FIND_FLAGS="-mtime -7"
-size +10M Files larger than 10MB readonly DEFAULT_FIND_FLAGS="-size +10M"
-newer file Modified more recently than file readonly DEFAULT_FIND_FLAGS="-newer /tmp/lastrun"
-name pattern Name matching (use with care) readonly DEFAULT_FIND_FLAGS="-name '*.txt'"

Examples:

# Skip hidden directories in search
readonly DEFAULT_FIND_FLAGS="-not -path '*/\\.*'"

# Find only regular files (not symlinks)
readonly DEFAULT_FIND_FLAGS="-type f"

# Find files modified in last 24 hours
readonly DEFAULT_FIND_FLAGS="-mtime -1"

# Combine multiple find options
readonly DEFAULT_FIND_FLAGS="-type f -not -path '*/\\.*' -mtime -7"

When to Use:

  • Limiting search to recently modified files
  • Excluding specific types (directories, symlinks, etc.)
  • Performance optimization for large directory trees
  • Integrating with monitoring systems

DEFAULT_SED_FLAGS - Custom Sed Options

Additional command-line flags to pass to the sed (stream editor) utility for text replacement.

Default Value: "" (empty string)

Purpose: Add sed-specific options that affect how replacements are processed without changing the core replacement logic.

Useful Sed Flags:

Flag Description Example
-e Multiple scripts readonly DEFAULT_SED_FLAGS="-e"
-E Extended regex (GNU) / -E (BSD) readonly DEFAULT_SED_FLAGS="-E"
-r Extended regex (GNU sed only) readonly DEFAULT_SED_FLAGS="-r"
-n Suppress automatic printing readonly DEFAULT_SED_FLAGS="-n"
--unbuffered Unbuffered output readonly DEFAULT_SED_FLAGS="--unbuffered"

Important Note: Most users should NOT modify this, as the script handles sed configuration internally.

Examples:

# Use extended regex support (GNU sed)
readonly DEFAULT_SED_FLAGS="-r"

# On macOS, use extended regex
readonly DEFAULT_SED_FLAGS="-E"

# Enable unbuffered output for large files
readonly DEFAULT_SED_FLAGS="--unbuffered"

Platform-Specific Configurations:

# For GNU/Linux systems
readonly DEFAULT_SED_FLAGS="-r"

# For BSD/macOS systems  
readonly DEFAULT_SED_FLAGS="-E"

# For systems where sed is gsed (GNU sed on macOS)
readonly SED_TOOL="gsed"
readonly DEFAULT_SED_FLAGS="-r"

When to Use:

  • Compatibility issues between GNU sed and BSD sed
  • Performance optimization for very large files
  • Debugging replacement issues
  • Cross-platform script execution

DEFAULT_GREP_FLAGS - Custom Grep Options

Additional command-line flags to pass to the grep utility for pattern matching and occurrence counting.

Default Value: "-F" (Fixed string matching - literal text, not regex)

Purpose: Control how grep searches for patterns in files. The default -F flag treats search patterns as literal strings, which is safer and faster when you don't need regex features.

Understanding the Default:

  • -F (Default): Fixed string matching
    • Treats the pattern as literal text
    • No regex special characters are interpreted
    • Faster processing
    • Safer for patterns containing regex metacharacters
    • Example: sr \"test*file\" \"replacement\" searches for literal "test*file"

Useful Grep Flags:

Flag Description When to Use
-F Fixed string (default) Pattern contains regex special chars or needs literal matching
-G Basic regex Using basic regex syntax
-E Extended regex Using extended regex with |, +, ?, etc.
-P Perl regex Most powerful regex support (if available)
-i Case-insensitive Should match regardless of case
-c Count matches Show number of matching lines
-l List filenames Show only files with matches
-o Only matching Show only the matched parts
-H Show filenames Always prefix with filename
-r Recursive Search directories

Examples:

# Use extended regex (enables \|, +, ?, etc.)
readonly DEFAULT_GREP_FLAGS="-E"

# Case-insensitive fixed string matching
readonly DEFAULT_GREP_FLAGS="-F -i"

# Perl regex support (most compatible)
readonly DEFAULT_GREP_FLAGS="-P"

# Count-only mode
readonly DEFAULT_GREP_FLAGS="-F -c"

# Extended regex with case-insensitive
readonly DEFAULT_GREP_FLAGS="-E -i"

Regex Type Comparison:

Type Example Pattern Use Case
Fixed (-F) test.file Literal matching; fastest
Basic (-G) test\\.file Minimal regex features
Extended (-E) test\\.file\|test_file Most common regex
Perl (-P) test\\.file|test_file Fullfeatures (not always available)

When to Change from Default (-F):

# When using regex patterns with pipe operator
readonly DEFAULT_GREP_FLAGS="-E"  # For patterns like: (pattern1|pattern2)

# When you need to match special characters dynamically
readonly DEFAULT_GREP_FLAGS="-E"  # For patterns with +, ?, *, etc.

# When case-insensitive search is required
readonly DEFAULT_GREP_FLAGS="-F -i"  # Keep fixed string, add case-insensitive

Performance Implications:

  • -F (Fastest): Fixed string matching is most efficient
  • -G (Medium): Basic regex is slower than fixed
  • -E (Slower): Extended regex requires more processing
  • -P (Slowest): Perl regex is most powerful but slowest

Security Consideration:

Using -F by default is a security best practice because it prevents unintended regex interpretation if user input is passed as a pattern.

Flag Combinations for Common Scenarios

Fast Processing (Large Files)

readonly DEFAULT_FIND_FLAGS="-type f"
readonly DEFAULT_SED_FLAGS=""
readonly DEFAULT_GREP_FLAGS="-F"  # Literal matching is fastest

Powerful Regex Support

readonly DEFAULT_FIND_FLAGS="-type f"
readonly DEFAULT_SED_FLAGS="-r"   # GNU sed extended regex
readonly DEFAULT_GREP_FLAGS="-E"  # Extended grep

Cross-Platform Compatibility (macOS/Linux)

readonly SED_TOOL="gsed"          # Install gnu-sed via Homebrew
readonly DEFAULT_SED_FLAGS="-r"
readonly DEFAULT_GREP_FLAGS="-E"

Legacy System (Minimal Regex)

readonly DEFAULT_FIND_FLAGS=""
readonly DEFAULT_SED_FLAGS=""
readonly DEFAULT_GREP_FLAGS="-F"  # Stick with fixed strings

Clone this wiki locally