PhotonSR

README

PhotonSR

CLI and Interactive TUI tool written in Go to search and replace text in files recursively with backup/restore functionality.

📝 Description

PhotonSR is a powerful, memory-efficient, and user-friendly text replacement tool that allows you to:

• Replace text patterns or regular expressions in files across directories.
• Use an interactive Text User Interface (TUI) wizard for a guided experience.
• Create automatic .bak backups before modifying files.
• Restore original files from these backups.
• Clean up (delete) all backup files in a directory.
• Simulate changes with a dry-run mode before committing.

The TUI mode is particularly helpful for users who prefer a step-by-step process, while the powerful CLI flags offer full control for scripting and automation.

✨ Features

• 🔄 Text & Regex Replacement - Replace literal strings or use the power of Regular Expressions.
• 🧙 Interactive Wizard Mode (TUI) - A user-friendly, step-by-step terminal interface for all operations (built with Bubble Tea).
• 💨 Large File Support - Memory-efficient streaming design handles large files with ease.
• 🛡️ Binary File Detection - Automatically detects and skips binary files to prevent corruption, with a --force override.
• 🔎 Dry Run Mode - Preview which files will be changed without making any modifications.
• 💾 Backup & Restore System - Auto-create .bak files before modification and restore them if needed.
• 🧹 Clean Backups - A simple command to delete all .bak files.
• 📁 Pattern Matching - Target files using wildcard patterns (e.g., *.txt, src/**/*.go).
• ⚠️ Interactive Safety Prompts - The CLI will ask for confirmation before performing destructive operations.

📥 Installation

Prerequisites

• curl or wget installed on your system.
• tar installed (for extracting the downloaded archive).

Easy Installation (Recommended)

You can install PhotonSR with a single command. The script will automatically detect your OS and architecture, download the latest version, and install it to a standard location (e.g., /usr/local/bin or $PREFIX/bin on Termux).

Using curl:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/atomiclogic/PhotonSR/main/install.sh)"

Using wget:

sh -c "$(wget -qO- https://raw.githubusercontent.com/atomiclogic/PhotonSR/main/install.sh)"

After installation, you might need to open a new terminal session for the photonsr command to be available.

Manual Installation (from Source)

1. Prerequisites: Go 1.24.2+ and Git.
2. Clone and Build:

   git clone https://github.com/arwahdevops/PhotonSR.git
   cd PhotonSR
   go build -o photonsr ./cmd
   

3. Install Manually: Move the photonsr binary to a directory in your PATH (e.g., sudo mv photonsr /usr/local/bin/).

🚀 Usage

PhotonSR can be run in two modes: CLI Mode (using command-line flags) or Wizard Mode (interactive TUI).

🧙 Wizard Mode (Interactive TUI)

This is the recommended mode for ease of use. It will guide you through all options, including Regex, Dry Run, and more.

To start the wizard mode, simply run:

photonsr

🖥️ CLI Mode

Use command-line flags for scripting or if you prefer direct commands.

Basic Command Structure

photonsr [OPTIONS] -old "SEARCH_TERM" -new "REPLACEMENT"
photonsr [OPTIONS] -restore
photonsr [OPTIONS] -clean

Common Options

Flag	Alias	Description	Applicable To
-wizard		Run in interactive wizard (TUI) mode.	(Mode selection)
-dir		Target directory (default: current directory .)	All operations
-pattern		Filename pattern to target (e.g., *.txt, main.*)	Replace
-old		Text or Regex pattern to search for.	Replace
-new		Text to replace the matched search term with.	Replace
-regex		Treat the -old pattern as a regular expression.	Replace
-backup		Create .bak backup files before modification.	Replace
-dry-run		Simulate the operation and show what would change without modifying files.	Replace
-force		Force processing of files that appear to be binary.	Replace
-restore		Restore files from .bak backups.	Restore
-clean		Delete all .bak files in the target directory.	Clean
-y		Skip interactive confirmation prompts for destructive operations.	All CLI Ops
-version		Show application version and exit.	(Global)

💡 Examples

1. Simple Replacement with Backup

Replaces "foo" with "bar" in all .md files, creating backups first.

photonsr -dir ./docs -pattern "*.md" -old "foo" -new "bar" -backup

2. Regex Replacement

Replaces email addresses with a placeholder in all .log files using a regex pattern.

photonsr -dir ./logs -pattern "*.log" -regex -old "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}" -new "[REDACTED]"

3. Dry Run Simulation

See which files would be modified if you replaced "http" with "https", without actually changing them.

photonsr -dir ./src -old "http://" -new "https://" -dry-run

4. Destructive Operation (Restore)

Restores original files from backups. The tool will ask for confirmation first.

photonsr -dir ./project -restore
> This will overwrite current files with their .bak versions. Are you sure? [y/N]: y

To skip the confirmation prompt in a script, use the -y flag:

photonsr -dir ./project -restore -y

📋 Important Notes

1. Safety First: The CLI will now prompt for confirmation before executing destructive operations (restore, clean, or replace without -backup). Use the -y flag to bypass this in scripts.
2. Binary Files: The tool automatically detects and skips binary files to prevent corruption. If you need to run on all files regardless of content, use the --force flag.
3. Regex Usage: When using the -regex flag, ensure your -old pattern is a valid Go regular expression. The replacement text in -new is treated as a literal string, but can use capture group variables like $1, $2, etc.
4. Large Files: Thanks to its streaming architecture, PhotonSR can handle very large files without consuming excessive memory.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

🙏 Acknowledgements

• Bubble Tea and the Charmbracelet ecosystem for making TUI development in Go delightful.