# DirectCompare User Guide

Welcome to DirectCompare -- a professional directory and file comparison tool that lets you compare files from multiple sources side by side.

---

## Getting Started

### Your First Comparison

1. Add two or more sources using the source input panel at the top of the window
2. Sources can be local folders, Git repos, GitHub repos, FTP servers, or archives
3. Click **Compare** to run the comparison
4. Results appear in the tree view below, colour-coded by status

### Source Types

| Source | How to Add | Example |
|--------|-----------|---------|
| Local folder | Browse or type a path | `C:\Projects\MyApp` |
| GitHub repo | Enter as `owner/repo@branch` | `torvalds/linux@master` |
| Git repository | Path to local repo with branch | `/repos/myproject@develop` |
| FTP / SFTP | Use the FTP connect dialog | `ftp://server.com/path` |
| Archive | Browse to a ZIP, 7Z, TAR, RAR, or ISO file | `C:\backups\release.zip` |

For GitHub and FTP sources, you'll be prompted for credentials if needed.

---

## Understanding Results

### Status Icons

Results are colour-coded to show the comparison status at a glance:

- **Identical** -- Files match across all sources
- **Different** -- File content differs between sources
- **Missing** -- File exists in some sources but not others
- **Newer Left / Newer Right** -- One side has a more recent modification date

### Filtering Results

Use the filter toolbar to show or hide result categories:

- **All** -- Show everything
- **Differences Only** -- Hide identical files
- **Identical Only** -- Show only matching files
- **Missing Only** -- Show files that exist in only some sources
- **Pattern Filter** -- Filter by filename pattern (e.g. `*.cpp`)

You can also use **Ctrl+F** to open the advanced filter dialog, or **Ctrl+Shift+S** to temporarily suppress all filters.

---

## Viewing Differences

Double-click any file in the results tree to open the **Diff Viewer**, which shows:

- Side-by-side text comparison with intra-line highlighting
- Syntax highlighting for common languages (C++, Python, JavaScript, HTML, etc.)
- Previous/Next difference navigation
- Option to collapse identical lines
- Hex view for binary files
- Image overlay for image files

---

## Comparing Specific File Types

### CSV / TSV Files
**Tools > Compare CSV/TSV Files** (Ctrl+Shift+C) opens a dedicated cell-by-cell comparison view for spreadsheet data.

### Images
**Tools > Compare Images** opens a visual overlay comparison. DirectCompare also includes perceptual image similarity detection (dHash and aHash) to find visually similar images even if resized or reformatted.

### Excel Files
Use the Excel comparison option under the Tools menu to compare `.xlsx` spreadsheets.

### 3D Models
STL and OBJ model files can be viewed with the built-in 3D viewer plugins.

---

## Merging Files

### 3-Way Merge
When comparing three sources, you can merge conflicts interactively:

1. Right-click a differing file and choose **Merge**
2. The merge dialog shows Base, Left, and Right versions
3. For each conflict, choose which version to keep
4. Save the merged result

### Folder Sync
Synchronise directories using **Tools > Sync**:

- **Left to Right** (Ctrl+Shift+Right) -- Copy newer/missing files from left to right
- **Right to Left** (Ctrl+Shift+Left) -- Copy newer/missing files from right to left
- Preview changes before applying

---

## Sessions and Bookmarks

### Sessions
Save your current comparison setup to return to it later:

- **Save Session** (Ctrl+S) -- Save sources, options, and results
- **Load Session** (Ctrl+Shift+O) -- Restore a previous session
- Sessions auto-save periodically so you don't lose work

### Bookmarks
Mark important files for quick access:

- **Save Current as Bookmark** (Ctrl+Shift+B) -- Bookmark the selected file
- **Manage Bookmarks** (Ctrl+B) -- View and navigate saved bookmarks

---

## Exporting Results

Export your comparison results in several formats:

| Format | Menu | Use Case |
|--------|------|----------|
| CSV | File > Export to CSV (Ctrl+E) | Spreadsheets, data analysis |
| HTML | File > Export to HTML | Shareable reports with formatting |
| JSON | File > Export to JSON | Automation, scripting |
| Patch | Tools > Generate Patch (Ctrl+Shift+P) | Apply differences with standard patch tools |

### Folder Report
**Session > Folder Compare Report** (Ctrl+Shift+R) generates a detailed summary of the comparison.

---

## Git and GitHub Integration

### GitHub Repositories
Compare GitHub repos without cloning:

1. Enter the repo as `owner/repo@branch` in a source field
2. DirectCompare fetches the file tree via the GitHub API
3. Set your GitHub token in settings for higher rate limits (5000 requests/hour vs 60)

### Local Git Repos
Compare branches, tags, or commits from local Git repositories:

1. Enter the repo path with a branch: `/path/to/repo@feature-branch`
2. DirectCompare reads Git objects directly via libgit2 -- no checkout needed

---

## Archive Support

DirectCompare can look inside archives and compare their contents:

**Supported formats:** ZIP, TAR, 7Z, RAR, ISO, CAB, GZ, BZ2, XZ

Simply add an archive file as a source. If the archive is password-protected, you'll be prompted for the password.

---

## Finding Duplicates

**Tools > Similarity Search** scans for similar files across your sources:

- **Text similarity** -- Finds files with similar content using Jaccard and line-based matching
- **Image similarity** -- Finds visually similar images using perceptual hashing

Set a similarity threshold (e.g. 80%) to control how closely files must match.

---

## Keyboard Shortcuts

### General
| Shortcut | Action |
|----------|--------|
| F1 | Help |
| Ctrl+Home | Home Screen |
| Ctrl+S | Save Session |
| Ctrl+Shift+O | Load Session |
| Ctrl+I | Compare Info |
| Ctrl+Z | Undo Last File Operation |
| Ctrl+T | New Session Tab |
| Ctrl+W | Close Session Tab |

### Comparison
| Shortcut | Action |
|----------|--------|
| Ctrl+Up | Compare Parent Folders |
| Ctrl+F | Filters |
| Ctrl+Shift+S | Suppress Filters |
| Ctrl+Shift+F | Compare Specific Files |
| Ctrl+Shift+G | Find Text in All Files |

### Export and Sync
| Shortcut | Action |
|----------|--------|
| Ctrl+E | Export to CSV |
| Ctrl+Shift+P | Generate Patch File |
| Ctrl+Shift+Right | Sync Left to Right |
| Ctrl+Shift+Left | Sync Right to Left |

### Bookmarks and Tools
| Shortcut | Action |
|----------|--------|
| Ctrl+B | Manage Bookmarks |
| Ctrl+Shift+B | Save Current as Bookmark |
| Ctrl+Shift+C | Compare CSV/TSV Files |
| Ctrl+H | View File Versions |
| Ctrl+R | Register License |

### Layout
| Shortcut | Action |
|----------|--------|
| Ctrl+L | Compact Layout |
| Ctrl+Shift+L | File Explorer Layout |
| Ctrl+Shift+D | Customise Columns |
| Ctrl+Shift+J | Comparison Profiles |

---

## Themes

DirectCompare includes three themes, toggled via **Tools > Toggle Theme**:

- **Light** -- Default bright theme
- **Dark** -- Reduced eye strain for extended use
- **Colorblind** -- Optimised colour palette for colour vision deficiency

---

## Licensing

DirectCompare offers several license tiers:

- **Basic** -- Core comparison features (free)
- **Trial** -- Full access for 30 days
- **Standard** -- Single user license
- **Premium** -- Advanced features including similarity search and merge
- **Enterprise** -- All features plus priority support
- **Lifetime** -- Perpetual license, all features

To register, go to **Help > Register** (Ctrl+R) and enter your license key.
To start a free trial, go to **Help > Start 30-Day Trial**.
To compare what each tier includes, go to **Help > Compare Tiers**.

---

## Troubleshooting

### "Failed to load image" errors
Ensure the application was able to initialise image handlers at startup. Try restarting DirectCompare.

### GitHub rate limit errors
Set a GitHub Personal Access Token via the GitHub authentication dialog (under Tools) to increase your rate limit from 60 to 5000 requests per hour.

### Archive password errors
Different archive formats handle passwords differently. If extraction fails, verify the password is correct and try again.

### Files not appearing in results
Check your active filters -- you may have a pattern or status filter hiding results. Press Ctrl+Shift+S to temporarily suppress all filters.

---

## Getting Help

- **F1** -- Opens this help guide
- **Help > Submit Bug Report** -- Send a bug report or feature request
- **Email** -- dircomparepro@gmail.com

Detailed bug reports with steps to reproduce are greatly appreciated and may be rewarded with license upgrades.
