This project has been archived by its maintainers, and is no longer receiving any updates.
Find and Replace
A command-line tool for finding and replacing text in files using regular expressions. This tool provides an intuitive interface for bulk text operations across your project files.
Features
- Regular Expression Support: Use regex patterns for complex search and replace operations
- Glob Pattern Matching: Find files using glob expressions like
*.py,config.*, etc. - Recursive Search: Search through directory trees with the
-r/--recursiveflag - Interactive Confirmation: Review matches before making changes (unless using
--no-confirm) - Dry Run Mode: Preview what would be changed without making actual modifications
- Error Handling: Graceful handling of permission errors, encoding issues, and invalid regex patterns
- Cross-Platform: Works on Windows, macOS, and Linux
Quick Start
Installation
Install from PyPI:
pip install find-replace-cli
Basic Usage
Replace all instances of "old_function" with "new_function" in Python files:
find-and-replace "*.py" /path/to/project "old_function" "new_function"
Common Examples
Replace text in all files recursively:
find-and-replace "*.txt" . "hello.*world" "hi universe" -r
Update version strings in configuration files:
find-and-replace "config.json" ~/projects "\"version\":\s*\"[^\"]*\"" "\"version\": \"2.0.0\"" -r
Dry run to preview changes:
find-and-replace "*.py" . "old_pattern" "new_pattern" --dry-run
No confirmation prompts (automation-friendly):
find-and-replace "*.md" . "old_text" "new_text" -r -n
Use Cases
- Code Refactoring: Rename functions, variables, or classes across your codebase
- Configuration Updates: Update configuration values across multiple files
- Documentation Maintenance: Update links, references, or terminology in documentation
- Migration Tasks: Update import statements, API calls, or deprecated syntax
- Bulk Text Processing: Any scenario requiring consistent text changes across multiple files
Safety Features
- Interactive Confirmation: By default, the tool shows you what will be changed and asks for confirmation
- Dry Run Mode: Test your patterns without making any changes
- Detailed Output: See exactly what files were processed and how many matches were found
- Error Recovery: Continues processing other files even if one file encounters an error
Command Line Arguments
find-and-replace FILE_PATTERN DIRECTORY FIND_PATTERN REPLACE_TEXT [OPTIONS]
Positional Arguments:
FILE_PATTERN: Glob pattern for file names (e.g.,*.py,config.*)DIRECTORY: Directory to search inFIND_PATTERN: Regular expression pattern to findREPLACE_TEXT: Text to replace matches with (supports regex groups like\1,\2)
Options:
-r, --recursive: Search subdirectories recursively-n, --no-confirm: Skip confirmation prompts--dry-run: Show what would be changed without making changes-h, --help: Show help message
Getting Help
- Documentation: Read the full documentation at find-and-replace.readthedocs.io
- Issues: Report bugs or request features on GitHub Issues
- Source Code: View the source code on GitHub
License
This project is licensed under the MIT License - see the LICENSE file for details.
Reference
This document provides detailed information about the find-and-replace CLI tool's components and functions.
Command Line Interface
Syntax
find-and-replace FILE_PATTERN DIRECTORY FIND_PATTERN REPLACE_TEXT [OPTIONS]
Arguments
Positional Arguments
FILE_PATTERN
: Glob pattern for matching file names
: Type: str
: Examples: *.py, *.txt, config.*, package.json
: Description: Supports standard glob wildcards (*, ?, [...])
DIRECTORY
: Directory to search in
: Type: str
: Examples: ., /path/to/project, ~/documents
: Description: Can be absolute or relative path. Tilde (~) expansion is supported.
FIND_PATTERN
: Regular expression pattern to search for
: Type: str
: Examples: old_function, hello.*world, "version":\s*"[^"]*"
: Description: Full Python regex syntax supported. Remember to escape special characters in shell.
REPLACE_TEXT
: Replacement text (can include regex groups)
: Type: str
: Examples: new_function, hi universe, "version": "2.0.0"
: Description: Supports backreferences (\1, \2, etc.) for captured groups.
Optional Arguments
-r, --recursive
: Search subdirectories recursively
: Type: flag
: Default: False
: Description: When enabled, searches through all subdirectories.
-n, --no-confirm
: Skip confirmation prompts
: Type: flag
: Default: False
: Description: Useful for automation scripts. Applies changes without user interaction.
--dry-run
: Show what would be changed without making actual changes
: Type: flag
: Default: False
: Description: Safe way to test patterns before applying them.
-h, --help
: Show help message and exit
: Type: flag
Regular Expression Examples
Basic Patterns
hello: Matches literal text "hello"hello.*world: Matches "hello" followed by anything, then "world"\d+: Matches one or more digits\w+: Matches one or more word characters
Advanced Patterns
"version":\s*"[^"]*": Matches JSON version fieldsimport\s+(\w+): Captures module names in import statementsfunction\s+(\w+)\s*\(: Captures function names
Replacement Examples
new_function: Simple text replacement\1_new: Prepend "new_" to captured group 1"version": "2.0.0": Replace with specific version
Error Handling
The tool handles various error conditions gracefully:
- File not found: Skips missing files with warning
- Permission denied: Reports permission errors and continues
- Unicode decode errors: Skips binary files with informative message
- Invalid regex: Validates patterns before processing
- Keyboard interrupt: Clean exit on Ctrl+C
Performance Considerations
- Files are processed sequentially
- Entire file content is loaded into memory
- Regex compilation is done once per pattern
- Large files (>100MB) may cause memory issues
Best Practices
- Test with
--dry-runbefore making actual changes - Use version control to track changes
- Escape shell metacharacters in patterns
- Start with simple patterns and build complexity gradually
- Use
--no-confirmonly for tested, automated scripts
Metadata
Release files for find-replace-cli 0.1.1.post3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| find_replace_cli-0.1.1.post3.tar.gz | 8.2 kB | Without provenance | Details for find_replace_cli-0.1.1.post3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| find_replace_cli-0.1.1.post3-py3-none-any.whl | Python 3 | none | any | Details for find_replace_cli-0.1.1.post3-py3-none-any.whl |
Total release size: 16.4 kB
Release files / find_replace_cli-0.1.1.post3.tar.gz
| Download URL | find_replace_cli-0.1.1.post3.tar.gz |
|---|---|
| Size | 8.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
23f41414df954641396454433dcd576d12430b5deb846eb05c7a75587367bfd2
|
|
BLAKE2b-256 checksum How to use checksums |
9d033df198401314d9bb6d26914ec4a07fb791619fa69fe465e73b99384010ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.13.5 Linux/6.11.0-1018-azure
|
Release files / find_replace_cli-0.1.1.post3-py3-none-any.whl
| Download URL | find_replace_cli-0.1.1.post3-py3-none-any.whl |
|---|---|
| Size | 8.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d53220a6cd8c0f30094c1991794d43b9a388f78ba139518d74cfcbcff771f0cf
|
|
BLAKE2b-256 checksum How to use checksums |
015f42dec231c193943a33a33a83231b89322232cd947e97a8b3e634cbd55993
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.13.5 Linux/6.11.0-1018-azure
|
Security for find-replace-cli 0.1.1.post3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.