gx

A fast file search and batch rename tool written in Go.

（This project code is generated by AI, then checked and corrected by human.）

Features

• find: Fast file content search (inspired by ripgrep)

  • Multi-threaded search
  • Regular expression support
  • Colored output with highlighting
  • Line number display
  • File filtering by glob pattern
  • Binary file detection

• replace: Fast file content search and replace (inspired by ripgrep)

  • Multi-threaded search and replace
  • Regular expression support
  • Colored output with highlighting
  • Line number display
  • File filtering by glob pattern
  • Binary file detection
  • Dry-run mode for safe preview
  • Intuitive argument parsing (2-argument smart mode)

• rename: Batch file renaming tool (inspired by f2)

  • Regular expression matching
  • Capture group replacement ($1, $2, etc.)
  • Dry-run mode (preview before executing)
  • Conflict detection
  • Directory support
  • Force mode for resolving conflicts
  • Case-insensitive file system support

Project Structure

gx/
├── cmd/
│   ├── replace/       # File content search and replace command
│   └── rename/        # Batch file rename command
├── args/              # Shared argument parsing functionality
├── regex/             # Regular expression matching wrapper
├── walker/            # Concurrent file system traversal
├── README.md          # English documentation
├── README_ZH.md       # Chinese documentation
└── LICENSE            # MIT License

Key Components

• args: Provides common argument parsing with support for:

  • Simple 2-argument mode (pattern + path or pattern + replacement)
  • Option handling with short and long forms
  • Automatic help generation

• regex: Wraps Go's regexp package with:

  • Case-insensitive matching
  • Fixed string support
  • Capture group replacement

• walker: Concurrent file system traversal with:

  • Directory skipping (.git, node_modules, etc.)
  • Glob pattern filtering
  • Binary file detection

Installation

go install github.com/azhai/gx@latest

Or build from source:

git clone https://github.com/azhai/gx.git
cd gx
make build

Usage

gx - A collection of file utilities

Usage: gx <command> [OPTIONS] [ARGS...]

Commands:
  find    Search for patterns in files (like grep)
  replace Search and replace text in files
  rename  Batch rename files

Use "gx <command> --help" for more information about a command.

find - File Content Search

# Basic search
gx find "pattern"                    # Search in current directory
gx find "pattern" /path/to/dir       # Search in specific directory

# Search options
gx find -F "pattern"                 # Treat pattern as literal string
gx find -g "*.go" "func"             # Search only in Go files
gx find -i "pattern"                 # Case insensitive search
gx find -j 4 "pattern"               # Use 4 worker threads
gx find -n "pattern"                 # Show line numbers (default)
gx find -N "pattern"                 # Hide line numbers
gx find --no-color "pattern"         # Disable colored output

# Examples
gx find "TODO" src/                  # Search for TODO in src/
gx find -i "error" -g "*.go"         # Case insensitive search in Go files
gx find "TODO" src/ test/            # Search in multiple directories

replace - File Content Search and Replace

# Basic search and replace
gx replace "pattern" "replace"       # Preview replace (dry-run)
gx replace "pattern" "replace" -x    # Execute replacement

# Using explicit options
gx replace -f "pattern" -r "replace" # Explicit find and replace
gx replace -f "TODO" -r "FIXME" -x   # Execute replacement

# Replace options
gx replace -F "pattern" "replace"    # Treat pattern as literal string
gx replace -g "*.go" "func" "FUNC"   # Replace only in Go files
gx replace -i "pattern" "replace"    # Case insensitive search
gx replace -j 4 "pattern" "replace"  # Use 4 worker threads
gx replace -n "pattern" "replace"    # Show line numbers (default)
gx replace -N "pattern" "replace"    # Hide line numbers
gx replace --no-color "pattern" "replace"  # Disable colored output
gx replace -x                        # Execute replacement (default: dry-run)

# Examples
gx replace "TODO" "FIXME"            # Preview: replace TODO with FIXME
gx replace "foo" "bar" -x            # Execute: replace all 'foo' with 'bar'
gx replace -F "[test]" "demo" -x     # Replace literal string '[test]'
gx replace -i "error" "warning" -g "*.go" -x  # Case insensitive in Go files

rename - Batch File Renaming

# Basic usage
gx rename "foo" "bar"                # Preview: replace 'foo' with 'bar' (dry-run)
gx rename "foo" "bar" /path/to/dir   # With specific directory

# Using explicit options
gx rename -f "pattern" -r "replace"  # Explicit find and replace
gx rename -f "foo" -r "bar" -x       # Execute rename

# Options
gx rename -d                         # Include directories
gx rename -F "pattern" "replace"     # Treat pattern as literal string
gx rename -g "*.jpg" "pattern" "replace"  # Filter by file pattern
gx rename -i "pattern" "replace"     # Case insensitive matching
gx rename -x                         # Execute (default: dry-run)
gx rename --force                    # Force rename even with conflicts

# Examples
gx rename "foo" "bar"                # Preview: replace 'foo' with 'bar'
gx rename "foo" "bar" -x             # Execute: replace 'foo' with 'bar'
gx rename "\.txt$" ".md" -x          # Change .txt to .md extension
gx rename "(\d+)" "prefix_$1" -x     # Add prefix to numbers
gx rename -i "IMG" "img" -g "*.jpg"  # Case conversion for jpg files
gx rename "^" "2024_" -x             # Add date prefix to all files
gx rename -F "[test]" "demo" -x      # Replace literal string '[test]'

Build from Source

git clone https://github.com/azhai/gx.git
cd gx
make build

Or use Makefile targets:

make gx        # Build gx binary
make clean     # Remove old binaries
make upx       # Build and compress with upx

Running Tests

go test ./... -v

License

MIT License - see LICENSE file for details.

Acknowledgments

• find/replace inspired by ripgrep
• rename inspired by f2