Skip to content

FAQ

Jump to bottom
Mikhail Deynekin edited this page Dec 23, 2025 · 1 revision

Frequently Asked Questions (FAQ)

Table of Contents

Installation & Setup

Q: What are the system requirements for sr-search-replace?

A: sr-search-replace is designed to work on:

  • Operating Systems: Windows, Linux, macOS
  • PHP Version: 7.4 or higher (8.0+ recommended)
  • Dependencies: Standard PHP extensions (PCRE for regex support)
  • Disk Space: Minimal (< 5 MB for installation)

Q: How do I install sr-search-replace?

A: Installation steps:

# Clone the repository
git clone https://github.com/paulmann/sr-search-replace.git
cd sr-search-replace

# Install dependencies (if using Composer)
composer install

# Make executable (Linux/macOS)
chmod +x sr-search-replace

Q: Can I install sr-search-replace globally?

A: Yes. After cloning, symlink the binary to your system PATH:

sudo ln -s /path/to/sr-search-replace/sr-search-replace /usr/local/bin/sr-search-replace

Q: What PHP modules are required?

A: The tool requires:

  • pcre (for regex pattern matching)
  • spl (Standard PHP Library)
  • reflection (for code analysis features) Most standard PHP installations include these by default.

Basic Usage

Q: What does sr-search-replace do?

A: sr-search-replace is a powerful search and replace utility that allows you to:

  • Search for text patterns using regular expressions or literal strings
  • Replace matches with new content
  • Process single files or entire directory trees
  • Preview changes before applying them
  • Maintain backup copies of modified files

Q: How do I perform a simple search and replace?

A: Basic usage:

sr-search-replace --find="pattern" --replace="replacement" --file="path/to/file"

Q: Can I use regular expressions?

A: Yes. Enable regex mode with the --regex or -r flag:

sr-search-replace -r --find="pattern\d+" --replace="NUM-$1" --file="test.txt"

Q: How do I process multiple files?

A: Use the recursive flag:

sr-search-replace --find="old" --replace="new" --directory="/path" --recursive

Q: What's the difference between case-sensitive and case-insensitive search?

A:

  • Case-sensitive (default): Matches exact character case
  • Case-insensitive: Use -i flag to ignore case:
sr-search-replace -i --find="Hello" --replace="Hi" --file="test.txt"

Advanced Features

Q: How do I preview changes before applying them?

A: Use the --dry-run or -d flag:

sr-search-replace --dry-run --find="old" --replace="new" --file="file.txt"

This shows what would be changed without modifying the file.

Q: Can I create automatic backups?

A: Yes. Enable backup with the --backup flag:

sr-search-replace --backup --find="old" --replace="new" --file="file.txt"

Backups are created with .bak extension.

Q: How do I use capturing groups in regex?

A: Use parentheses for groups and $1, $2, etc. for replacement:

sr-search-replace -r --find="(\w+)@(\w+\.\w+)" --replace="$1 [$2]" --file="emails.txt"

Q: Can I apply multiple search-replace operations?

A: Yes. Create a configuration file:

# replacements.yml
replacements:
  - find: "old1"
    replace: "new1"
  - find: "old2"
    replace: "new2"

Then run:

sr-search-replace --config="replacements.yml" --file="target.txt"

Q: What about word boundaries in regex?

A: Use \b for word boundaries:

sr-search-replace -r --find="\bword\b" --replace="replacement" --file="file.txt"

Q: How do I handle special characters?

A: Escape them with backslash or use raw strings:

sr-search-replace --find="\$amount" --replace="\$price" --file="config.php"

Troubleshooting

Q: I'm getting "File not found" error. What should I do?

A: Common causes:

  1. Check the file path is correct
  2. Verify file permissions (must be readable)
  3. Use absolute paths when possible:
sr-search-replace --find="old" --replace="new" --file="/absolute/path/file.txt"

Q: My regex pattern isn't matching anything. Why?

A: Troubleshooting steps:

  1. Enable dry-run to check without making changes
  2. Test your regex pattern separately
  3. Ensure you're using double backslashes: \d not single slash
  4. Check for hidden characters in your search pattern
  5. Verify case sensitivity settings

Q: How do I handle encoding issues (UTF-8, etc.)?

A: The tool handles UTF-8 by default. For other encodings:

sr-search-replace --encoding="ISO-8859-1" --find="pattern" --replace="new" --file="file.txt"

Q: Can I undo changes after applying them?

A: Yes, if backup was enabled:

sr-search-replace --restore --file="file.txt"

Otherwise, use version control or your backup strategy.

Q: What does the "Permission denied" error mean?

A: The tool doesn't have write access. Solutions:

  1. Check file ownership: ls -l filename
  2. Change permissions: chmod 644 filename
  3. Run with elevated privileges if necessary (use caution)

Q: Performance is slow on large files. How can I improve it?

A: Optimization strategies:

  1. Use specific patterns instead of broad matches
  2. Process smaller chunks with --line-by-line
  3. Disable backup if not needed: --no-backup
  4. Use character classes instead of alternation: [abc] not (a|b|c)

Performance & Optimization

Q: How does sr-search-replace handle very large files?

A: The tool implements efficient streaming for large files:

  • Memory usage is optimized through buffering
  • Line-by-line processing available with --line-by-line
  • Typical performance: 10MB+ files in seconds

Q: What's the recommended regex optimization?

A: Best practices:

  • Use specific patterns: [0-9]{3} is faster than .*\d.*
  • Avoid unnecessary quantifiers: a* vs a+
  • Use atomic groups for complex patterns: (?>group)
  • Test performance with dry-run first

Q: Can I parallelize operations across multiple files?

A: Yes, the --parallel flag enables multi-threading:

sr-search-replace --parallel --find="pattern" --replace="new" --directory="/path" --recursive

Integration & Automation

Q: How do I integrate sr-search-replace in CI/CD pipelines?

A: Example for GitHub Actions:

- name: Search and Replace
  run: |
    sr-search-replace --find="VERSION=.*" --replace="VERSION=1.2.3" --file="config.txt"

Q: Can I use sr-search-replace in PHP code?

A: Yes, require the library:

require 'vendor/autoload.php';
use Paulmann\SearchReplace\Engine;

$engine = new Engine();
$result = $engine->replace('old', 'new', '/path/to/file');

Q: How do I add sr-search-replace to my project?

A: Via Composer:

composer require paulmann/sr-search-replace

Q: Can I create custom filters for file selection?

A: Yes, use extension filters:

sr-search-replace --find="pattern" --replace="new" --directory="/path" --extensions="php,js,css" --recursive

Best Practices

Q: What's the safest way to use sr-search-replace?

A: Recommended workflow:

  1. Always use --dry-run first
  2. Ensure backups are enabled
  3. Test on a small sample first
  4. Review the preview output carefully
  5. Use version control (git, etc.)
  6. Keep a separate backup of original files
  7. Document all changes in commit messages

Q: Should I use regex for simple text replacements?

A: No. Use literal mode for simple cases:

# Good - clear intent
sr-search-replace --find="hello" --replace="hi" --file="test.txt"

# Avoid unnecessary complexity
sr-search-replace -r --find="hello" --replace="hi" --file="test.txt"

Q: How do I handle version-controlled files safely?

A: Best practice:

# Always use dry-run first
sr-search-replace --dry-run --find="old" --replace="new" --directory="." --recursive

# Then apply with git awareness
git add -A
sr-search-replace --find="old" --replace="new" --directory="." --recursive --backup
git diff --stat

Q: What about testing replacements?

A: Create a test environment:

# Copy files to test directory
cp -r original/ test/

# Run replacement on test copies
sr-search-replace --find="pattern" --replace="new" --directory="test" --recursive

# Verify results
diff -r original/ test/

Support & Contribution

Q: Where can I report bugs or issues?

A: Use the GitHub Issues tracker:

  • sr-search-replace Issues
  • Include: error message, command used, minimal reproduction case
  • Attach sample files if possible (sanitized for confidentiality)

Q: How can I contribute to sr-search-replace?

A: Contributions are welcome!

  1. Fork the repository
  2. Create a feature branch
  3. Write tests for new features
  4. Submit a pull request with description
  5. See Contributing Guidelines

Q: Is there commercial support available?

A: For commercial support inquiries:

  • Email: sr@devnekin.com
  • Subject: "Commercial Support - sr-search-replace"
  • Responses typically within 24-48 hours

Q: What's the project license?

A: sr-search-replace is licensed under the MIT License. See LICENSE file for details. You're free to:

  • Use commercially
  • Modify the source
  • Distribute As long as you include the original license and copyright notice.

Q: How often is the project updated?

A: Development cycle:

  • Critical bug fixes: immediate
  • Feature releases: every 2-4 weeks
  • Major versions: as needed (typically quarterly)
  • Security updates: highest priority

Additional Resources

Last Updated: 2025 Maintained by: Paul Mann Community: GitHub Issues and Discussions

Clone this wiki locally