PT - Production-hardened Clipboard to File Tool

A robust command-line tool for managing clipboard content with intelligent file versioning, backup management, and recursive search capabilities.

🚀 Features

Core Functionality

• ✅ Clipboard to File - Save clipboard content to files instantly
• ✅ Smart Backup System - Automatic versioning with timestamps and comments
• ✅ Recursive File Search - Find files anywhere in subdirectories
• ✅ Check Mode - Skip writes when content is identical (save disk space)
• ✅ Append Mode - Add clipboard content to existing files
• ✅ Comment Support - Add descriptive comments to all operations

Advanced Features

• 🌳 Directory Tree View - Visualize directory structure with gitignore support
• 📦 Backup Management - List, restore, and compare backup versions
• 🔍 Delta Integration - Beautiful side-by-side diffs using delta CLI
• 🗑️ Safe Deletion - Backup files before deletion with empty placeholder
• ⚙️ Configuration System - Customize behavior via YAML config
• 📊 Metadata Storage - Track backup comments, timestamps, and origins

Security & Validation

• 🔒 Path traversal protection
• 🔒 System directory write protection
• 🔒 File size limits (configurable, default 100MB)
• 🔒 Filename length validation
• 🔒 Disk space checking

📦 Installation

From Source

# Clone repository

git clone https://github.com/cumulus13/pt.git

cd pt


# Build release binary

cargo build --release


# Binary will be at: target/release/pt


# Optional: Install to system

cargo install --path .

From Crates.io (when published)

cargo install pt-cli

🎯 Quick Start

# Write clipboard to file

pt notes.txt


# Write with check mode (skip if identical)

pt notes.txt -c


# Write with comment

pt notes.txt -m "Initial draft"


# Append clipboard to file

pt append log.txt

pt append log.txt -m "New entry"


# List all backups

pt list notes.txt


# Restore from backup (interactive)

pt restore notes.txt


# Restore last backup

pt restore notes.txt --last


# Compare with backup using delta

pt diff notes.txt

pt diff notes.txt --last


# Show directory tree

pt tree

pt tree /path/to/dir

pt tree -e node_modules,.git


# Configuration

pt config init          # Create sample config

pt config show          # View current settings

pt config path          # Show config location


# Version info

pt -V

pt --version-info

📖 Command Reference

Write Operations

# Basic write

pt <filename>                    # Write clipboard to file

pt <filename> -c                 # Check mode (skip if identical)

pt <filename> -m "comment"       # With comment

pt <filename> -c -m "comment"    # Check mode with comment

Append Mode

pt append <filename>             # Append clipboard

pt append <filename> -m "msg"    # Append with comment

Backup Management

pt list <filename>               # List all backups

pt restore <filename>            # Interactive restore

pt restore <filename> --last     # Restore last backup

pt restore <filename> -m "msg"   # Restore with comment

pt diff <filename>               # Interactive diff

pt diff <filename> --last        # Diff with last backup

File Operations

pt remove <filename>             # Delete file (with backup)

pt remove <filename> -m "msg"    # Delete with comment

Directory Tree

pt tree [path]                   # Show tree (default: .)

pt tree -e file1,file2           # Exclude files/dirs

Configuration

pt config init [path]            # Create config (default: pt.yml)

pt config show                   # Display current config

pt config path                   # Show config file location

⚙️ Configuration

Create a pt.yml file in one of these locations:

• ./pt.yml (current directory)
• ~/.config/pt/pt.yml
• ~/pt.yml

Sample Configuration

# PT Configuration File

# Maximum clipboard content size in bytes (default: 104857600 = 100MB)
max_clipboard_size: 104857600

# Maximum number of backups to keep (default: 100)
max_backup_count: 100

# Maximum filename length (default: 200)
max_filename_length: 200

# Backup directory name (default: "backup")
backup_dir_name: backup

# Maximum directory depth for recursive search (default: 10)
max_search_depth: 10

Generate sample config:

pt config init

📂 Backup System

Backup Location

All backups are stored in the ./backup/ directory (configurable).

Backup Naming

Format: {filename}_{ext}.{timestamp}.{pid}_{random}

Example: notes_txt.20241115_143022123456.12345_a3f4

Backup Metadata

Each backup includes a .meta.json file containing:

{
  "comment": "User-provided comment",
  "timestamp": "2024-11-15T14:30:22+07:00",
  "size": 1234,
  "original_file": "/path/to/original.txt"
}

🔍 Recursive Search

When a file is not found in the current directory, PT automatically searches subdirectories (up to configured depth).

# File in subdirectory

pt src/main.rs


# If multiple files found, interactive selection:

🔍 Found 3 file(s):


1. ./src/main.rs - 2024-11-15 14:30:22 - 15.2 KB

2. ./backup/main.rs - 2024-11-14 10:20:15 - 14.8 KB

3. ./old/main.rs - 2024-11-10 09:15:30 - 13.5 KB


Enter file number to use (1-3) or 0 to cancel: 

🎨 Delta Integration

PT supports delta for beautiful diffs:

# Install delta

cargo install git-delta


# Use with PT

pt diff notes.txt

Features:

• Syntax highlighting
• Line numbers
• Side-by-side or unified diff
• Customizable themes

🌳 Tree View

Display directory structure with file sizes:

pt tree


myproject

├── src/

│   ├── main.rs (15.2 KB)
│   └── lib.rs (8.5 KB)
├── Cargo.toml (245 B)
└── README.md (3.1 KB)

2 directories, 4 files, 27.0 KB total

Gitignore Support

Tree view respects .gitignore patterns automatically.

Exceptions

Exclude specific files/directories:

pt tree -e node_modules,.git,target

🔒 Security Features

1. Path Validation

   • Blocks path traversal (..)
   • Prevents system directory writes
   • Filename length limits

2. Size Limits

   • Configurable max clipboard size
   • File size validation before operations

3. Backup Limits

   • Automatic cleanup of old backups
   • Configurable retention count

🚦 Exit Codes

• 0 - Success
• 1 - Error (with descriptive message)

🐛 Troubleshooting

Clipboard Access Issues

Linux: Install xclip or xsel

sudo apt-get install xclip

# or

sudo apt-get install xsel

macOS: Should work out of the box

Windows: Should work out of the box

Delta Not Found

Install delta for diff functionality:

cargo install git-delta

Permission Denied

Check write permissions:

ls -la .

chmod u+w filename.txt

📊 Examples

Daily Workflow

# Morning: Start notes

pt notes.txt -m "Daily standup notes"


# Throughout day: Append updates

pt append notes.txt -m "Meeting outcome"

pt append notes.txt -m "Action items"


# Review changes

pt diff notes.txt --last


# If needed, restore previous version

pt list notes.txt

pt restore notes.txt


# End of day: Archive

mv notes.txt archive/notes_$(date +%Y%m%d).txt

Code Snippets

# Quick code snippet storage

pt snippets/query.sql -m "User analytics query"

pt snippets/script.sh -m "Deployment script v1"


# Later: Review and compare

pt list snippets/query.sql

pt diff snippets/query.sql

Project Documentation

# Save clipboard content to docs

pt docs/api.md -c -m "API documentation update"


# Tree view of docs

pt tree docs


# Restore if needed

pt restore docs/api.md --last

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

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

MIT License

Copyright (c) 2025 Hadi Cahyadi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

💻 Author

Hadi Cahyadi

• GitHub: @cumulus13
• Email: cumulus13@gmail.com

Made with ❤️ by Hadi Cahyadi

Your complete file version management system with contextual history in a single command. ⚡

If you find PT useful, consider supporting its development and please consider giving it a star on GitHub! ⭐:

Support me on Patreon

🙏 Acknowledgments

• clipboard - Clipboard access
• clap - CLI argument parsing
• delta - Beautiful diffs
• walkdir - Directory traversal

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions