Workspace - Command-Line Tool Suite

Workspace is a tool suite for file operations, version management, and development workflow automation. Includes refac (string replacement), scrap (local trash folder), unscrap (file restoration), and st8 (automatic versioning).

View on GitHub

Usage Guide

This guide covers all aspects of using the Workspace tool suite for string replacement, line analysis, project cleanup, and version management.

Tools Overview

Refac - String Replacement Tool

refac <ROOT_DIR> <OLD_STRING> <NEW_STRING> [OPTIONS]

Ldiff - Line Difference Visualizer

ldiff [SUBSTITUTE_CHAR]

Scrap - Local Trash Tool

scrap [FILE/DIR] [SUBCOMMAND] [OPTIONS]

Unscrap - File Restoration Tool

unscrap [FILE/DIR] [OPTIONS]

St8 - Version Management Tool

st8 [SUBCOMMAND] [OPTIONS]

Refac - String Replacement

Command Syntax

refac <ROOT_DIR> <OLD_STRING> <NEW_STRING> [OPTIONS]

Simple Examples

# Replace in current directory
refac . "oldname" "newname"

# Process specific directory
refac ./src "OldClass" "NewClass"

# Preview changes first (recommended)
refac . "oldname" "newname" --verbose

Operation Modes

Refac operates on two levels by default:

  1. Name Replacement: Renames files and directories
  2. Content Replacement: Replaces strings inside text files

Mode Flags

Use these flags to limit the operation scope:

# Only rename files/directories (skip content)
refac . "oldname" "newname" --names-only

# Only replace content (skip renaming)
refac . "oldname" "newname" --content-only

# Only process files (skip directories)
refac . "oldname" "newname" --files-only

# Only process directories (skip files)
refac . "oldname" "newname" --dirs-only

Safety Features

Dry Run Mode

Always preview changes before applying them:

# See what would be changed
refac . "oldname" "newname" --verbose

# Dry run with verbose output
refac . "oldname" "newname" --verbose --verbose

Backup Files

Create backups before modifying files:

# Create .bak files before modification
refac . "oldname" "newname" --backup

Force Mode

Skip confirmation prompts:

# Apply changes without confirmation
refac . "oldname" "newname" --force

Filtering Options

Include Patterns

Process only files matching specific patterns:

# Only Rust files
refac . "oldname" "newname" --include "*.rs"

# Multiple patterns
refac . "oldname" "newname" --include "*.rs" --include "*.toml"

# Include hidden files
refac . "oldname" "newname" --include ".*"

Exclude Patterns

Skip files matching specific patterns:

# Exclude log files
refac . "oldname" "newname" --exclude "*.log"

# Exclude multiple patterns
refac . "oldname" "newname" --exclude "target/*" --exclude "*.log"

# Exclude build directories
refac . "oldname" "newname" --exclude "node_modules/*" --exclude "dist/*"

Combining Filters

# Include source files but exclude tests
refac ./src "oldname" "newname" \
  --include "*.rs" \
  --include "*.toml" \
  --exclude "*test*"

Options

Depth Control

Limit how deep the tool searches:

# Search only current directory (depth 1)
refac . "oldname" "newname" --max-depth 1

# Search up to 3 levels deep
refac . "oldname" "newname" --max-depth 3

Threading

Control parallel processing:

# Use 8 threads for faster processing
refac . "oldname" "newname" --threads 8

# Auto-detect optimal thread count (default)
refac . "oldname" "newname" --threads 0

Case Sensitivity

# Case-insensitive matching
refac . "oldname" "newname" --ignore-case

Regex Patterns

Use regular expressions for complex patterns:

# Use regex patterns
refac . "old_\w+" "new_name" --regex

# Case-insensitive regex
refac . "old.*name" "newname" --regex --ignore-case

Output Formats

Human-Readable (Default)

refac . "oldname" "newname"

Shows colored output with progress bars and detailed information.

JSON Output

refac . "oldname" "newname" --format json

Useful for scripting and automation:

{
  "summary": {
    "content_changes": 15,
    "file_renames": 8,
    "directory_renames": 3,
    "total_changes": 26
  },
  "result": "success",
  "dry_run": false
}

Plain Text

refac . "oldname" "newname" --format plain

Simple text output without colors or special formatting.

Real-World Examples

Code Refactoring

# Rename a class throughout a project
refac ./src "UserManager" "AccountManager" --verbose

# Update variable names in specific files
refac ./src "oldVar" "newVar" --include "*.js" --include "*.ts"

# Rename function across codebase
refac . "calculateTotal" "computeSum" --content-only

File Organization

# Rename draft files to final
refac ./docs "draft" "final" --names-only

# Update configuration URLs
refac ./config "old.example.com" "new.example.com" --content-only

# Rename project files
refac . "myproject" "newproject" --exclude "node_modules/*"

Database Migration

# Update table names in SQL files
refac ./sql "old_table" "new_table" --include "*.sql"

# Update column references
refac ./src "old_column" "new_column" --include "*.py" --include "*.sql"

Best Practices

1. Always Test First

# Review changes carefully (refac shows preview automatically)
refac . "oldname" "newname" --verbose --verbose

# Check the output carefully before proceeding
refac . "oldname" "newname"

2. Use Version Control

# Commit before refactoring
git add .
git commit -m "Before refactoring: rename oldname to newname"

# Run refac
refac . "oldname" "newname"

# Review changes
git diff

3. Be Specific with Patterns

# Good: Specific file types
refac ./src "oldname" "newname" --include "*.rs" --include "*.toml"

# Better: Also exclude unwanted directories
refac ./src "oldname" "newname" \
  --include "*.rs" \
  --exclude "target/*" \
  --exclude "*.log"

4. Use Appropriate Modes

# When renaming files only
refac . "old_prefix" "new_prefix" --names-only

# When updating configuration values
refac ./config "old.server.com" "new.server.com" --content-only

5. Handle Large Projects

# Use more threads for large codebases
refac . "oldname" "newname" --threads 8

# Limit scope with patterns
refac . "oldname" "newname" --include "src/**" --exclude "tests/**"

Troubleshooting

No Changes Found

# Use verbose mode to see what's being processed
refac . "oldname" "newname" --verbose --verbose

# Check if the string exists
grep -r "oldname" . --include="*.rs"

# Verify include/exclude patterns
refac . "oldname" "newname" --include "*" --verbose

Permission Errors

# Check file permissions
ls -la problematic_file

# Use sudo if necessary (be careful!)
sudo refac . "oldname" "newname"

Binary Files

Refac automatically skips binary files for content replacement:

# Use verbose to see skipped files
refac . "oldname" "newname" --verbose

Large Files

For very large files, increase available memory:

# Process in smaller batches
refac . "oldname" "newname" --max-depth 2

Integration with Other Tools

Git Hooks

Create a pre-commit hook to validate changes:

#!/bin/bash
# .git/hooks/pre-commit
refac . "debug_print" "logger.debug" --verbose --format json | \
  jq '.summary.total_changes > 0' && \
  echo "Warning: debug prints found"

CI/CD Pipelines

# Check for outdated patterns
refac . "old_api_url" "new_api_url" --verbose --format json | \
  jq '.summary.total_changes > 0' && exit 1

Scripts

#!/bin/bash
# bulk-rename.sh
PATTERNS=(
  "old_function_1:new_function_1"
  "old_function_2:new_function_2"
  "old_variable:new_variable"
)

for pattern in "${PATTERNS[@]}"; do
  IFS=':' read -r old new <<< "$pattern"
  echo "Replacing $old with $new..."
  refac . "$old" "$new" --force
done

Ldiff - Line Difference Visualizer

The ldiff tool processes input lines, replacing repeated tokens with a substitute character to highlight patterns and differences.

Basic Usage

# Read from stdin with default substitute character
echo -e "hello world\nhello universe" | ldiff
# Output:
# hello world
# ░░░░░ universe

# Use custom substitute character
echo -e "test line\ntest another" | ldiff "*"
# Output:
# test line
# **** another

Log Analysis

# Monitor system logs for patterns
tail -f /var/log/syslog | ldiff

# Analyze web server logs
cat /var/log/nginx/access.log | ldiff "■"

# Find patterns in application logs
journalctl -u myapp | ldiff

Command Output Analysis

# Analyze directory listings
find /usr/local -type f | ldiff

# Monitor process lists
ps aux | ldiff

# Analyze network connections
netstat -tulpn | ldiff "●"

Real-time Monitoring

# Monitor multiple log files
tail -f /var/log/app1.log /var/log/app2.log | ldiff

# Watch system messages
dmesg -w | ldiff

# Monitor command output
watch -n 2 "df -h" | ldiff

Advanced Usage

# Save patterns to file
cat large.log | ldiff > patterns.txt

# Combine with other tools
grep "ERROR" /var/log/app.log | ldiff | head -20

# Chain multiple filters
cat access.log | grep "GET" | ldiff "*" | tee filtered.log

Use Cases

Security Analysis:

# Monitor failed login attempts
tail -f /var/log/auth.log | grep "Failed" | ldiff

Performance Monitoring:

# Track response time patterns
tail -f /var/log/api.log | grep "response_time" | ldiff

System Administration:

# Analyze startup patterns
dmesg | grep "systemd" | ldiff

Development Debugging:

# Monitor application output
./my_app 2>&1 | ldiff

Scrap - Local Trash Can

The scrap tool provides a local trash can for deleted files using a .scrap folder.

Basic Operations

# Move files to local trash can
scrap temp_file.txt old_directory/

# List contents (default behavior)
scrap

# Search for files
scrap find "*.log"

# Clean old items
scrap clean --days 30

# Archive everything
scrap archive --remove

Workflow Examples

# Development workflow - move unwanted files to trash
scrap debug.log temp_output/ experimental_code/
# Continue working...
scrap clean --days 7  # Weekly cleanup

# Remove old files to trash instead of deleting
scrap old_version/ deprecated_files/
scrap archive --output "project-backup-v1.0.tar.gz"

For detailed information, see the Scrap Tool Guide.

Unscrap - File Restoration

The unscrap tool restores files from .scrap back to their original locations.

Basic Operations

# Restore last scrapped item
unscrap

# Restore specific file
unscrap filename.txt

# Restore to custom location
unscrap file.txt --to /new/location/

# Force overwrite existing files
unscrap file.txt --force

Workflow Examples

# Quick recovery
scrap important.txt  # Accidental scrap
unscrap              # Quick undo

# Selective restoration
scrap list           # See what's available
unscrap old_config.json --to ./backup/

For detailed information, see the Unscrap Tool Guide.

St8 - Version Management

Installation and Setup

# Navigate to your git repository
cd your-project/

# Install git hook
st8 install

# Check status
st8 status

Basic Operations

# Show current version information
st8 show

# Manual version update
st8 update

# Force update (outside git repo)
st8 update --no-git

# Check configuration and status
st8 status

# Uninstall hook
st8 uninstall

Configuration

Create .st8.json in your repository root:

{
  "version": 1,
  "enabled": true,
  "version_file": "version.txt"
}

Version Calculation

St8 calculates versions using:

# Example with git tag v1.0 and 3 commits since tag:
# Result: 1.0.3.247 (where 247 is total changes)

Workflow Examples

# Setup new project
git init
git add .
git commit -m "Initial commit"
git tag v1.0
st8 install

# Normal development (automatic)
echo "new feature" >> main.rs
git add .
git commit -m "Add feature"  # Version auto-updated

# Check current version
st8 show
cat version.txt

# Manual version check
st8 update --no-git

For detailed information, see the St8 Tool Guide.

Tool Integration

Combined Workflows

# development workflow
st8 install                               # Set up versioning
scrap temp_* *.log build/                    # Clear workspace
refac . "OldClass" "NewClass" --verbose      # Preview changes
refac . "OldClass" "NewClass"                # Apply changes
git add . && git commit -m "Refactor class" # Auto-version bump

# Safe refactoring with backup
scrap old_implementation.rs                  # Backup current code
st8 show                                 # Note current version
refac . "OldClass" "NewClass" --verbose      # Preview changes
refac . "OldClass" "NewClass"                # Apply changes
# If issues arise: unscrap old_implementation.rs

# Project cleanup and maintenance
scrap temp_* debug_* old_*/                  # Move temporary files
refac . "old_project_name" "new_project_name" # Rename project
scrap clean --days 14                       # Clean old scrapped files
st8 status                               # Check version tracking

Automation Scripts

#!/bin/bash
# safe-refactor.sh - refactoring workflow
OLD="$1"
NEW="$2"

# Check st8 is set up
if ! st8 status >/dev/null 2>&1; then
    echo "Setting up version tracking..."
    st8 install
fi

# Record current version
CURRENT_VERSION=$(st8 show 2>/dev/null | grep "Full Version" | cut -d: -f2 | xargs)
echo "Current version: $CURRENT_VERSION"

# Backup current state
echo "Creating backup..."
scrap archive --output "backup-$(date +%s).tar.gz"

# Preview changes
echo "Previewing changes..."
refac . "$OLD" "$NEW" --verbose

# Ask for confirmation
read -p "Apply changes? (y/N) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
    refac . "$OLD" "$NEW"
    echo "Refactoring complete!"
    
    # Commit changes (triggers version bump)
    git add .
    git commit -m "Refactor: $OLD -> $NEW"
    
    # Show new version
    NEW_VERSION=$(cat version.txt 2>/dev/null || echo "unknown")
    echo "Version updated: $CURRENT_VERSION -> $NEW_VERSION"
else
    echo "Operation cancelled."
fi

Next Steps