Histree

A powerful command-line tool for managing directory history with interactive time-based navigation, enhanced diff functionality, and safe exploration capabilities.

Features

• Interactive TUI: User-friendly interface for time point selection
• Git Integration: Full Git commit history support
• File-based Tracking: Fallback to file modification times for non-Git directories
• Safe Sandbox Restoration: Explore past states without affecting current files
• Enhanced Diff: Content-aware file comparison with statistics
• Manual Snapshots: Create custom time points for important milestones
• Configuration Management: Customizable settings and themes
• Cross-platform: Works on Windows, macOS, and Linux
• Performance Optimized: Smart caching and efficient file scanning

Commands

Core Commands

• histree list - List available time points with interactive TUI
• histree goto [id/date] - Restore directory to a time point in sandbox
• histree diff [id/date] - Diff current directory against a time point

Advanced Commands

• histree snapshot [message] - Create a manual snapshot of current state
• histree restore [id/date] - Restore current directory to a time point (DANGEROUS)
• histree config [key] [value] - View or modify configuration settings

Usage

Basic Operations

# List all time points (interactive)
histree list

# List with different formats
histree list --format=table
histree list --format=json
histree list --limit=10

# Go to a specific time point
histree goto abc123
histree goto 2024-01-15
histree goto 2024-01-15 14:30

# Diff against a time point
histree diff abc123
histree diff 2024-01-15

Advanced Operations

# Create a manual snapshot
histree snapshot "Before major refactor"
histree snapshot "After fixing critical bug"

# Restore directory (with backup)
histree restore abc123

# Manage configuration
histree config                    # Show all settings
histree config verbose true      # Enable verbose logging
histree config sandbox_dir /tmp  # Set custom sandbox directory

Configuration

Histree automatically creates a configuration file at ~/.config/histree/config.json:

{
  "sandbox_dir": "/tmp/histree-sandbox",
  "date_format": "2006-01-02 15:04",
  "cache_duration": "5m",
  "verbose": false,
  "git_mode": true,
  "file_mode": true,
  "theme": {
    "primary_color": "cyan",
    "secondary_color": "yellow",
    "border_style": "double"
  }
}

Configuration Options

• sandbox_dir: Directory for sandbox operations
• date_format: Date format for display
• cache_duration: How long to cache file information
• verbose: Enable verbose logging
• git_mode: Enable Git history tracking
• file_mode: Enable file modification tracking

Examples

Git Repository

cd /path/to/git/repo
histree list                    # Shows Git commits
histree goto HEAD~1            # Explore previous commit
histree diff HEAD~2            # See changes from 2 commits ago

Non-Git Directory

cd /path/to/regular/directory
histree list                    # Shows file modification times
histree snapshot "Important checkpoint"
histree goto 2024-01-15        # Explore state from specific date

Workflow Example

# 1. Check what time points are available
histree list

# 2. Create a snapshot before making changes
histree snapshot "Before implementing new feature"

# 3. Make some changes to files...

# 4. See what changed
histree diff "Before implementing new feature"

# 5. Explore the previous state safely
histree goto "Before implementing new feature"

# 6. If you want to actually restore (dangerous!)
histree restore "Before implementing new feature"

Installation

# Clone the repository
git clone https://github.com/meliodas113/histree.git
cd histree

# Build
go build -o histree

# Install (optional)
go install

Dependencies

• Go 1.24.2+
• Git (optional, for Git repository support)

Safety Features

• Sandbox Mode: Default goto command never modifies your current files
• Backup Creation: restore command automatically creates backups
• Confirmation Prompts: Dangerous operations require explicit confirmation
• File Type Detection: Smart handling of different file types and sizes

Performance

• Smart Caching: File modification times cached for 5 minutes
• Efficient Scanning: Only scans directories when necessary
• Content Comparison: Intelligent file comparison with size and content checks
• Memory Optimized: Minimal memory footprint for large directories

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.