XLSX Compare Extension
A VS Code extension for comparing XLSX files with git commits, specifically designed for Oracle Intelligent Advisor development workflows.
Features
- 🎯 Default XLSX Editor - Automatically becomes the default viewer for all
.xlsx files in VS Code
- 📊 Intelligent Git Integration - Seamlessly integrates with VS Code's git extension for diff operations
- � Standalone File Comparison - Compare any two XLSX files without requiring git
- �🔍 Excel-like Diff Viewer - Custom grid showing additions (green), deletions (red), modifications (yellow)
- 📈 Multi-worksheet Support - Handle complex Excel files with multiple sheets
- 🔧 Formula Change Detection - See changes in Excel formulas, not just values
- 📋 Context Menu Integration - Right-click any .xlsx file to compare
- ⚡ Automatic Diff Detection - Works with staged changes, commit comparisons, and file history
Installation
- Clone this repository
- Run
npm install to install dependencies
- Run
npm run compile to build the extension
- Press F5 to open a new Extension Development Host window
- Test the extension with your XLSX files
Usage
Automatic Git Integration
Once installed, this extension becomes the default editor for all .xlsx files in VS Code. This means:
- Git diff operations automatically open in the XLSX diff viewer
- Staged changes can be viewed by clicking on XLSX files in the Source Control panel
- Commit history comparisons work seamlessly when browsing git logs
- File comparisons work directly from VS Code's built-in git features
Manual Comparison Commands
The extension provides multiple ways to compare XLSX files, accessible via right-click context menu or Command Palette (Ctrl+Shift+P):
1. Compare XLSX: Compare two git commits
- Purpose: Compare any XLSX file between two different git commits
- Usage:
- Right-click on any
.xlsx file → "Compare XLSX: Compare two git commits"
- Or use Command Palette: "Compare XLSX: Compare two git commits"
- What it does: Opens a picker to select two commits and shows the differences between them
2. Compare XLSX: Compare current file with Git HEAD (Latest Commit)
- Purpose: Compare the current working version with the latest committed version
- Usage:
- Right-click on any
.xlsx file → "Compare XLSX: Compare current file with Git HEAD"
- Or use Command Palette: "Compare XLSX: Compare current file with Git HEAD"
- What it does: Instantly compares your current file with the HEAD commit
3. Compare XLSX: Compare any two files
- Purpose: Compare any two XLSX files from anywhere on your system (no git required)
- Usage:
- Right-click on any
.xlsx file → "Compare XLSX: Compare any two files"
- Or use Command Palette: "Compare XLSX: Compare any two files"
- Or from Command Palette without selecting a file first
- What it does: Opens file pickers to select two XLSX files for comparison
- Perfect for: Non-git workflows, comparing files from different locations, or comparing backups
4. Two-Step File Selection (New!)
- Purpose: Select one file, then easily compare others against it (like a "clipboard" for comparisons)
- Step 1: Right-click any
.xlsx file → "Compare XLSX: Select file for comparison"
- Step 2: Right-click any other
.xlsx file → "Compare XLSX: Compare with selected file"
- Benefits:
- Compare multiple files against the same reference file
- No need to re-select the first file each time
- Great for comparing several variations against an original
- Clear visual feedback showing which file is selected
Git Integration Examples
- View staged changes: Click on any XLSX file in the "Staged Changes" section
- View working directory changes: Click on any XLSX file in the "Changes" section
- Compare commits: Use the Git Graph or Git History extensions, then click on XLSX files
- Review pull requests: XLSX files in PR diffs automatically open in the custom viewer
Non-Git Usage Examples
- Compare different versions: Select any two XLSX files from your file system
- Compare backups: Compare current file with backup copies
- Cross-project comparison: Compare files from different folders or drives
- Template comparison: Compare a customized file with its original template
How It Works
XLSX Parsing
- Uses the
xlsx library to parse Excel files into structured data
- Handles multiple worksheets, formulas, and cell values
- Preserves formula information (shows
=SUM(A1:A10) rather than just the result)
Git Integration
- Extracts XLSX files from any git commit using
git show
- Supports relative paths and workspace detection
- Handles binary file extraction properly
Diff Visualization
- Green cells: Added content
- Red cells: Deleted content
- Yellow cells: Modified content
- Sheet-level changes: New/deleted worksheets
- Formula highlighting: Distinguishes formulas from values
Perfect for Oracle Intelligent Advisor
This extension is specifically designed for teams working with:
- Excel-based rule authoring with full git integration
- Spreadsheet version control with automatic diff detection
- Collaborative spreadsheet development with seamless VS Code integration
- Excel file change tracking that works with all git workflows
- Code review processes involving XLSX files
Why This Matters for OIA Development
Traditional git diff tools show XLSX files as binary blobs with no meaningful comparison. This extension:
- Reveals actual content changes in rules, decision tables, and data structures
- Shows formula modifications that affect business logic
- Tracks worksheet additions/deletions that represent new rule sets
- Integrates with standard git workflows without requiring separate tools
Technical Details
Architecture
- Extension Host: Main VS Code extension logic
- XLSX Comparer: Core comparison engine using xlsx.js
- Git Integration: Command-line git integration for file extraction
- Webview Provider: Custom UI for displaying diffs
File Support
.xlsx files (Excel 2007+ format)- Multiple worksheets
- Formulas and values
- Git repositories
Development
Building
npm install
npm run compile
Testing
npm run test
Packaging
npm run package
Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request
Requirements
- VS Code 1.74.0 or higher
- Git installed and accessible from command line
- Workspace must be a git repository for comparison features
Important Notes
- Automatic Setup: The extension automatically registers as the default editor for
.xlsx files
- Git Integration: Works seamlessly with VS Code's built-in git features and popular git extensions
- No Configuration Required: Start using immediately after installation
Known Limitations
- Binary Excel files only (
.xlsx, not .xls)
- Requires git command-line tools
- Large files may take time to process
- Formatting/styling changes not yet detected
Development & Testing
If you're developing with this extension:
Build the extension:
npm run compile
Create sample XLSX files for testing:
npm run create-sample
Test scenarios:
- Open any
.xlsx file to see automatic diff integration
- Use git staging to test staged changes comparison
- Navigate git history to test commit comparisons
- Try manual commands from Command Palette for specific comparisons
Contributing
Feel free to contribute improvements or report issues on the project repository.
License
MIT License - see LICENSE file for details.
