feat: add comparison mode and improve CLI options

- Add explicit mode flag (-m) to control comparison behavior
- Remove auto-detection of commit mode
- Update CLI help text with mode-specific examples

Author: bayuagpr-xaltius

.gitignore

@@ -40,4 +40,7 @@ Thumbs.db
 # Optional
 *.log
 *.pid
-*.seed
+*.seed
+
+# GitLoom Diff
+/git-diffs

README.md

@@ -33,45 +33,33 @@ gitloom-diff -s feature/awesome -e main
 
 ## Why You'll Love This
 
-GitHub, GitLab, or any other git provider diffs can be hard to parse - especially for large changes. This tool gives you a better diff experience with:
-
-- 🚀 **Beautiful Local Diffs**
-  - Works with any git provider
-  - Syntax highlighting
-  - Clean, consistent formatting
-
-- 📝 **Markdown Export Ready For**:
-  - 📄 Documentation & issue tracking
-  - 🤖 AI code review (ChatGPT, Claude)
-  - 📊 PR summaries & release notes
-  - 🔍 Security audits
-
-- 🔧 **Full IDE Power**:
-  - 🔍 Fast full-text search
-  - 🎯 Regex & pattern matching
-  - 🌳 File tree navigation
-  - 🖼️ Rich markdown preview
-  - 🔖 Bookmarking changes
-
-## Features In Detail
-
-- 📊 **Smart Analysis**
-  - Per-file change statistics
-  - Commit message history
-  - File diff summaries
-  - Progress tracking for large diffs
-
-- 🧹 **Intelligent Filtering**
-  - Excludes build artifacts
-  - Skips dependency files
-  - Removes sensitive data
-  - Customizable patterns
-
-- 💡 **Flexible Comparison**
-  - Between any commits
-  - Across branches
-  - Between tags
-  - With remote branches
+GitHub, GitLab, or any other git provider diffs are often overwhelming - endless scrolling, no search, and hard to navigate between files. This tool generates clean markdown diffs that you can:
+
+- 🚀 **Open in Your Favorite IDE/Editor**
+  - Use your IDE's search & navigation
+  - Navigate diffs with familiar codebase structure (follows original file paths)
+  - Get proper syntax highlighting
+  - Review diffs comfortably
+
+- 🤖 **Feed Directly to AI**
+  - Compatible with any LLM (e.g. ChatGPT, Claude, etc)
+  - Review changes with integrated AI in your preferred editor (No more copy-paste hell)
+  - Let AI help you:
+    - Generate PR summaries instantly
+    - Generate commit messages from changes
+    - Get code review suggestions and explanations
+    - Analyze changes for potential bugs and improvements
+
+- 🧹 **Focus on What Matters**
+  - Auto-skips node_modules, build files, and junk
+  - Shows only relevant changes
+  - Customize exclusion patterns
+
+## Core Features
+
+- 💡 **Compare Anything**: branches (local or remote), commits, tags
+- 📊 **Rich Statistics**: changes per file, summaries, commit history
+- 📝 **Markdown Output**: readable, searchable, navigable, shareable
 
 ## Output Structure
 
@@ -106,14 +94,14 @@ GitHub, GitLab, or any other git provider diffs can be hard to parse - especiall
 ### Basic Commands
 
 ```bash
-# Compare commits
-gitloom-diff -s abc123 -e def456
-
-# Compare branches
+# Compare branches (PR mode - default)
 gitloom-diff -s feature/branch -e main
 
-# Compare tags
-gitloom-diff -s v1.1.0 -e v1.0.0
+# Compare tags (use tag mode)
+gitloom-diff -s v1.1.0 -e v1.0.0 -m tag
+
+# Compare commits (use commit mode)
+gitloom-diff -s abc123 -e def456 -m commit
 
 # Compare with remote
 gitloom-diff -s origin/main -e main
@@ -131,23 +119,25 @@ Options:
   -o, --output <dir>         Output directory (default: "git-diffs")
   --exclude <patterns...>    Additional file patterns to exclude
   -f, --format <format>      Diff format: diff|unified|side-by-side
+  -m, --mode <mode>         Comparison mode: pr|commit|tag (default: "pr")
   --light-mode              Use light mode theme
   -h, --help                Display help
 ```
 
 ### Advanced Examples
 
 ```bash
-# Side-by-side diff with custom output
-gitloom-diff -s main -e develop -o pr-123-diffs -f side-by-side
+# Side-by-side tag comparison
+gitloom-diff -s v2.0.0 -e v1.0.0 -m tag -f side-by-side
 
-# Exclude patterns
-gitloom-diff --exclude "*.test.js" "docs/**"
+# Exclude patterns with commit comparison
+gitloom-diff -s abc123 -e def456 -m commit --exclude "*.test.js" "docs/**"
 
 # Multiple options
 gitloom-diff \
   -s feature/new-ui \
   -e develop \
+  -m pr \
   -o ui-changes \
   -f side-by-side \
   --exclude "*.test.js" "*.snap" \

src/cli/index.js

@@ -17,6 +17,7 @@ const pkg = require("../../package.json");
  *   - 'unified': Unified diff format
  *   - 'side-by-side': Two column comparison view
  * @param {boolean} [options.lightMode=false] - Use light mode theme instead of dark
+ * @param {string} [options.mode] - Comparison mode (pr, commit, tag)
  * 
  * Default behavior:
  * - Compares current branch against 'main' if no refs provided
@@ -56,22 +57,29 @@ program
   .option("--exclude <patterns...>", "Additional file patterns to exclude")
   .option("-f, --format <format>", "Diff format (diff, unified, side-by-side)", "diff")
   .option("--light-mode", "Use light mode theme instead of dark mode")
+  .option("-m, --mode <mode>", "Comparison mode (pr, commit, tag)", "pr")
   .addHelpText('after', `
 Examples:
   # Basic usage (current branch vs main)
   $ gitloom-diff
 
-  # Compare branches
+  # Compare branches (PR mode)
   $ gitloom-diff -s feature/awesome -e main
 
-  # Compare tags
-  $ gitloom-diff -s v1.1.0 -e v1.0.0
+  # Compare tags (use -m tag for proper tag comparison)
+  $ gitloom-diff -s v1.1.0 -e v1.0.0 -m tag
+
+  # Compare commits (use -m commit for commit comparison)
+  $ gitloom-diff -s abc123 -e def456 -m commit
 
   # Side-by-side diff with custom output
   $ gitloom-diff -s main -e develop -o pr-diffs -f side-by-side
 
-  # Compare commit hashes
-  $ gitloom-diff -s 1234567890abcdef1234567890abcdef12345678 -e 0987654321fedcba0987654321fedcba09876543`)
+Note:
+  Mode (-m) affects how git compares the references:
+  - pr: Uses double-dot (..) for PR/branch comparison
+  - commit: Uses triple-dot (...) for commit comparison
+  - tag: Uses triple-dot (...) for tag comparison`)
   .action(async (options) => {
     showBranding();
 
@@ -80,8 +88,7 @@ Examples:
       exclusions: options.exclude || [],
       diffFormat: options.format,
       darkMode: !options.lightMode,
-      // Auto-detect mode based on ref format
-      mode: (isCommitHash(options.startRef) && isCommitHash(options.endRef)) ? 'commit' : 'pr'
+      mode: options.mode
     };
 
     const differ = new GitLoomDiff(config);

src/sdk/GitLoomDiff.js

@@ -14,7 +14,7 @@ class GitLoomDiff {
    * @param {string[]} [options.exclude=[]] - File patterns to exclude from the diff
    * @param {string} [options.format='diff'] - Diff format (diff, unified, side-by-side)
    * @param {boolean} [options.darkMode=true] - Whether to use dark mode theme
-   * @param {string} [options.mode='pr'] - Diff mode ('pr' or 'commit')
+   * @param {string} [options.mode='pr'] - Diff mode ('pr', 'commit', or 'tag')
    */
   constructor(options = {}) {
     this.config = new Config(options);