Scrap Tool Guide

The scrap tool provides a local trash can using a .scrap folder for files you want to delete. It’s designed to safely handle files you want to remove from your workspace by moving them to a trash folder, with the ability to easily restore them later.

Core Concepts

The .scrap Folder

Automatically created in your current directory
Stores temporarily moved files and directories
Maintains metadata about original file locations
Automatically added to .gitignore if it exists

Metadata Tracking

Records original file paths for easy restoration
Timestamps when files were scrapped
Enables intelligent restoration and history tracking

Basic Operations

Moving Files to .scrap

# Move a single file
wsb scrap temp.log

# Move multiple files (run multiple commands)
wsb scrap file1.txt file2.txt old_directory/

# Move with absolute paths
wsb scrap /path/to/file.txt

# Automatic conflict resolution
wsb scrap file.txt  # Creates .scrap/file.txt
wsb scrap file.txt  # Creates .scrap/file_1.txt (automatic rename)

Listing Contents

# List all items (default behavior)
wsb scrap

# Explicit list command
wsb scrap list

# Sort by different criteria
wsb scrap list --sort name    # Alphabetical
wsb scrap list --sort date    # Most recent first
wsb scrap list --sort size    # Largest first

Example output:

Contents of .scrap folder:
--------------------------------------------------------------------------------
📄 temp.log               1.2 KB  2 hours ago     from: /home/user/project/temp.log
📁 old_code              15.3 MB  1 day ago       from: /home/user/project/old_code
📄 debug.txt              524 B   3 hours ago     from: /home/user/debug.txt

Features

Search and Find

# Search by filename (supports regex)
wsb scrap find ".*\.log"           # Find all .log files
wsb scrap find "test.*"            # Find files starting with "test"
wsb scrap find "backup"            # Simple string search

# Search in file contents too
wsb scrap find "TODO" --content    # Search for "TODO" in filenames and content
wsb scrap find "bug.*fix" --content # Regex search in content

Cleaning and Maintenance

# Remove items older than 30 days (default)
wsb scrap clean

# Remove items older than specific number of days
wsb scrap clean --days 7          # Remove items older than 1 week
wsb scrap clean --days 1          # Remove items older than 1 day

# Preview what would be removed (dry run)
wsb scrap clean --days 30 --verbose

# Remove ALL items from .scrap folder
wsb scrap purge

# Skip confirmation prompt
wsb scrap purge --force

Archive and Backup

# Archive .scrap contents to compressed file
wsb scrap archive

# Archive with custom filename
wsb scrap archive --output backup-2024.tar.gz
wsb scrap archive --output "backup-$(date +%Y%m%d).tar.gz"

# Archive and remove original files from .scrap
wsb scrap archive --remove

# Archive with custom name and remove
wsb scrap archive --output monthly-backup.tar.gz --remove

Workflow Examples

Daily Workspace Cleanup

# Move temporary files to .scrap
wsb scrap *.tmp *.log debug_output/

# List what's in .scrap
wsb scrap

# Clean items older than a week
wsb scrap clean --days 7

# Archive old items monthly
wsb scrap archive --output "archive-$(date +%Y-%m).tar.gz" --remove

Project Development

# Scrap old experimental code
wsb scrap experimental_feature/ old_tests/

# Search for specific files later
wsb scrap find "experimental.*"

# Restore if needed (using wsb unscrap)
wsb unscrap experimental_feature/

# Or clean up completely
wsb scrap purge --force

Code Refactoring

# Before major refactoring, scrap old implementations
wsb scrap old_implementation.rs legacy_tests/

# Check what you've scrapped
wsb scrap list --sort date

# If refactoring fails, restore old code
wsb unscrap old_implementation.rs

# If successful, clean up
wsb scrap clean --days 0  # Remove everything

Safety Features

Conflict Resolution

Automatic renaming: If a file with the same name exists in .scrap, it’s automatically renamed (e.g., file_1.txt, file_2.txt)
No overwrites: Never overwrites existing files
Atomic operations: File moves are atomic to prevent corruption

Confirmation Prompts

Destructive operations: wsb scrap purge asks for confirmation unless --force is used
Preview mode: wsb scrap clean --verbose shows what would be removed
Clear feedback: Always shows what actions were taken

Git Integration

Automatic .gitignore: Adds .scrap/ to .gitignore if the file exists
Repository safety: Never commits temporary files to version control
Seamless workflow: Works transparently in Git repositories

Metadata and History

The scrap tool maintains detailed metadata about all operations:

What’s Tracked

Original paths: Full path to where files came from
Timestamps: When files were moved to .scrap
Restore information: Data needed for intelligent restoration

Metadata File

Stored as .scrap/.metadata.json
JSON format for easy parsing
Automatically managed (no manual editing needed)
Used by wsb unscrap for restoration

Tips and Best Practices

Organization

# Use consistent naming for temporary files
wsb scrap temp_* debug_* test_*

# Regular cleanup schedule
wsb scrap clean --days 14  # Weekly cleanup of old items

Backup Strategy

# Monthly archives
wsb scrap archive --output "archive-$(date +%Y-%m).tar.gz" --remove

# Project-specific backups
wsb scrap archive --output "project-backup-v1.0.tar.gz"

Performance

The .scrap folder is excluded from most file operations
Metadata file is small and efficiently parsed
Large directories are moved atomically (not copied)

Integration with Other Tools

# Combine with find
find . -name "*.tmp" -exec wsb scrap {} \;

# Use in scripts
if [ -f "old_config.conf" ]; then
    wsb scrap old_config.conf
fi

Workspace - Command-Line Tool Suite