Skip to content

Quick Start Tutorial

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

Quick Start Tutorial

Get up and running with sr-search-replace in minutes. This guide focuses on the tool's core strength: simplified search and replace syntax with minimal parameters.

Table of Contents

Core Syntax

The simplified sr-search-replace syntax:

sr "<pattern>" "<replacement>" [path]

With file pattern matching:

sr "*.[extension]" "<find>" "<replace>"

Examples:

  • sr "*.txt" "old" "new" - Replace in all .txt files
  • sr "*.js" "const " "let " - Change variable declarations
  • sr "*.html" "<div>" "<section>" - Update HTML structure

Basic Commands (1 Minute)

These are the most essential sr-search-replace operations:

Single File Replacement

Replace text in a single file:

sr "old_text" "new_text" /path/to/file.txt

All Files with Extension

Replace across all files with specific extension:

sr "*.py" "old_name" "new_name"

Restore from Backup

Recover from a previous operation using automatic backups:

sr --restore /path/to/file.txt

This reverts the file to its state before the last replacement.

Show Help

Display all available options:

sr --help

Simple Replacements (5 Minutes)

Replace in Current Directory

Find and replace in all files in current directory:

sr "TODO" "DONE" *.md

Case-Sensitive Replacement

By default, replacement is case-sensitive:

sr "Error" "Warning" *.log

This matches only "Error", not "error" or "ERROR".

Replace Across Multiple File Types

Use glob patterns to target multiple extensions:

sr "deprecated_function" "new_function" *.{js,ts,jsx,tsx}

Working with Multiple Files (10 Minutes)

Recursive Search and Replace

Search entire directory tree:

sr "*.js" "console.log" "console.debug" --recursive ./src/

This processes all .js files in ./src/ and all subdirectories.

Exclude Directories

Skip certain directories (minified, compiled, etc.):

sr "*.js" "old" "new" --exclude "node_modules" --exclude ".git" --recursive .

Backup Before Replacing

Always create backups of modified files:

sr "*.java" "oldAPI" "newAPI" --backup --recursive /project/

Backups are saved with .bak extension.

Preview Changes First

See what will be changed before applying:

sr "*.sql" "UPDATE" "INSERT" --dry-run database/

No files are modified when using --dry-run.

Essential Features (15 Minutes)

Regular Expression Matching

Use regex for complex pattern matching:

sr --regex "function\\s+(\\w+)" "const $1 =" *.js

Matches function declarations and converts them to const assignments.

Case-Insensitive Replacement

Ignore case when matching:

sr --ignore-case "api" "API" *.md

This matches "api", "API", "Api", and replaces with "API".

Count Matches

View match count without making changes:

sr --count-only "TODO" *.js

Useful for auditing before replacement.

Show Context Around Matches

Display surrounding lines:

sr --context 3 "password" *.py

Shows 3 lines before and after each match.

Session Tracking

Track related replacements as a session:

sr "*.java" "OldClass" "NewClass" --session "refactor_v2.0" --backup
sr "*.xml" "oldProperty" "newProperty" --session "refactor_v2.0" --backup

All changes grouped under "refactor_v2.0" session.

Skip Binary Files

Automatically skip binary files:

sr "*.txt" "old" "new" --skip-binary --recursive .

Prevents corruption of image/compiled files.

Safe Search & Replace Workflow

Recommended workflow for production environments:

Step 1: Verify Pattern

First, test what will match:

sr --count-only "old_pattern" *.txt

Confirm number of matches.

Step 2: Preview Changes

See exact modifications without applying:

sr "old_pattern" "new_pattern" --dry-run --context 2 *.txt

Step 3: Review Session

Create backup before applying (automatic with --backup):

sr "old_pattern" "new_pattern" --backup --session "update_v1.2" *.txt

Step 4: Verify Results

Check that changes were applied correctly:

sr --count-only "new_pattern" *.txt

Count should match previous results.

Step 5: Confirm or Rollback

If needed, restore from backup:

sr --restore *.txt

Common Use Cases

Update Import Statements

Change module imports across project:

sr "*.py" "from old_module" "from new_module" --recursive .

Refactor Class Names

Rename classes with backup:

sr "*.java" "class OldName" "class NewName" --backup --recursive src/

Fix Typos in Documentation

Correct mistakes in markdown files:

sr "*.md" "occassion" "occasion" --recursive docs/

Update Configuration Values

Change settings across config files:

sr "*.conf" "timeout=300" "timeout=600" --backup /etc/

Remove Deprecated Code

Clean up deprecated imports:

sr "*.js" "import {oldFunc}" "// import {oldFunc}" --recursive src/

Migrate to New API

Update function calls:

sr "--regex" "oldAPI\\.call\\(" "newAPI.execute(" *.ts --backup --recursive

Troubleshooting

Pattern Not Matching

Try these steps:

  1. Use --count-only to verify matches exist:
sr --count-only "your_pattern" target_file
  1. Check for case sensitivity:
sr --ignore-case "your_pattern" "replacement" target_file
  1. Enable regex if using special characters:
sr --regex "your\\.pattern" "replacement" target_file

Unintended Replacements

  1. Preview first with --dry-run:
sr "pattern" "replacement" --dry-run --context 2 files
  1. Restore if needed:
sr --restore affected_file

Performance Issues

  1. For large directories, be selective:
sr "*.txt" "old" "new" --recursive data/  # Target specific directory
  1. Skip unnecessary file types:
sr "*.py" "old" "new" --skip-binary --exclude "*.pyc" --recursive .
  1. Use session tracking for complex operations:
sr "*.js" "old" "new" --session "update" --backup

Next Steps

Now that you understand the basics:

Clone this wiki locally