Diff Manifests VS Code Extension

English | 简体中文

A Visual Studio Code extension for comparing Android manifest files using the diffmanifests Python package. This extension provides a seamless integration of the diffmanifests CLI tool into VS Code, supporting Windows, Ubuntu and macOS platforms.

Features

🔍 Deep Manifest Comparison: Compare two manifest XML files directly from VS Code
📋 Sidebar View: Dedicated sidebar with quick access to all features and settings
⚡ Quick Actions: Compare manifests, check environment, and manage settings from sidebar
📂 Recent Files: Track and quickly access recently compared files
⚙️ Configurable: Customize Python path, config file, and output format
📊 Multiple Output Formats: Support for JSON, TXT, and Excel output formats
🔄 Auto-Installation: Automatically offers to install the diffmanifests package
📝 Output Panel: View detailed comparison logs and results
🌐 Cross-Platform: Works on Windows, Ubuntu, and macOS

Prerequisites

Visual Studio Code: Version 1.75.0 or higher
Python: Version 3.7 or higher with pip package manager
Node.js & npm: Version 16.x or higher (for building from source)

Installation

📖 For detailed platform-specific installation instructions, see INSTALL.md

Quick Install (Recommended)

Windows

# Install Python package
pip install diffmanifests

# Navigate to extension directory
cd C:\path\to\diffmanifests\vscode

# Build extension
npm install
npm run compile

# Package extension
npm install -g @vscode/vsce
vsce package

# Install in VS Code
code --install-extension diffmanifests-1.0.0.vsix

Ubuntu/Linux

# Install Python package
pip3 install diffmanifests

# Navigate to extension directory
cd /path/to/diffmanifests/vscode

# Build extension
npm install
npm run compile

# Package extension
npm install -g @vscode/vsce
vsce package

# Install in VS Code
code --install-extension diffmanifests-1.0.0.vsix

Installation Methods

Method 1: From VSIX File (Local Installation)

Build the extension:

cd vscode
npm install
npm run compile
vsce package

Install via command line:

code --install-extension diffmanifests-1.0.0.vsix

Or install via VS Code UI:
- Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)
- Type "Extensions: Install from VSIX"
- Select the generated .vsix file

Method 2: Development Mode (For Testing)

Open the vscode folder in VS Code
Press F5 to launch Extension Development Host
Test the extension in the new window

Method 3: From VS Code Marketplace (When Published)

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Search for "Diff Manifests"
Click Install

Post-Installation Setup

Configure Python Path

After installation, configure the Python path for your platform:

Windows (settings.json):

{
  "diffmanifests.pythonPath": "python"
}

Ubuntu/Linux (settings.json):

{
  "diffmanifests.pythonPath": "python3"
}

Verify Installation

# Check extension is installed
code --list-extensions | grep diffmanifests

# Check Python package is installed
pip show diffmanifests  # Windows
pip3 show diffmanifests  # Ubuntu/Linux

Usage

Click on the Diff Manifests icon in the Activity Bar (left sidebar)
In the sidebar, you'll see:
- Actions: Quick access to compare manifests and other operations
- Recent Files: List of recently compared files for quick access
- Settings: View and modify extension settings
- Quick Links: Access documentation and GitHub repository
Click "Compare Manifests" to start a new comparison
Follow the prompts to select files
View results in the output panel or open the result file

Method 2: Command Palette

Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)
Type "Diff Manifests: Compare Two Manifest Files"
Select the first manifest file (manifest1)
Select the second manifest file (manifest2)
Select or confirm the config file
Choose the output file location
View the results

Right-click on a manifest XML file in the Explorer
Select "Diff Manifests: Compare Selected Files"
Follow the prompts to select the second manifest and config file
Choose the output file location
View the results

Method 4: Using Settings

Configure default settings for faster workflow:

Open Settings (Ctrl+,)
Search for "diffmanifests"
Configure:
- Python Path (if not using system default)
- Default Config File path
- Output Format (JSON or Excel)
- Auto-install preference
- Output panel visibility

Configuration

📖 For detailed configuration instructions and examples, see CONFIGURATION_GUIDE.md

The extension provides the following configuration options:

Setting	Type	Default	Description
`diffmanifests.pythonPath`	string	`"python"`	Path to Python executable
`diffmanifests.packagePath`	string	`""`	Path to diffmanifests package (only used when Auto Install is off)
`diffmanifests.gerrit.url`	string	`"https://android-review.googlesource.com"`	Gerrit server URL
`diffmanifests.gerrit.user`	string	`""`	Gerrit username
`diffmanifests.gerrit.password`	string	`""`	Gerrit password/token
`diffmanifests.gerrit.queryOptions`	array	`["CURRENT_REVISION"]`	Gerrit query options
`diffmanifests.gitiles.url`	string	`"https://android.googlesource.com"`	Gitiles server URL
`diffmanifests.gitiles.user`	string	`""`	Gitiles username
`diffmanifests.gitiles.password`	string	`""`	Gitiles password/token
`diffmanifests.gitiles.timeout`	number	`-1`	Gitiles timeout in seconds, -1 for no timeout
`diffmanifests.gitiles.retry`	number	`1`	Gitiles retry attempts
`diffmanifests.outputFormat`	string	`".json"`	Output format (.json, .txt, or .xlsx)
`diffmanifests.autoInstall`	boolean	`true`	Auto-install diffmanifests if not found
`diffmanifests.showOutputPanel`	boolean	`true`	Show output panel when running

Example Configuration

Add to your settings.json:

{
  "diffmanifests.pythonPath": "python3",
  "diffmanifests.packagePath": "",
  "diffmanifests.gerrit.url": "https://android-review.googlesource.com",
  "diffmanifests.gerrit.user": "your-username",
  "diffmanifests.gerrit.password": "your-password-or-token",
  "diffmanifests.gerrit.queryOptions": ["CURRENT_REVISION"],
  "diffmanifests.gitiles.url": "https://android.googlesource.com",
  "diffmanifests.gitiles.user": "",
  "diffmanifests.gitiles.password": "",
  "diffmanifests.gitiles.timeout": -1,
  "diffmanifests.gitiles.retry": 1,
  "diffmanifests.outputFormat": ".json",
  "diffmanifests.autoInstall": true,
  "diffmanifests.showOutputPanel": true
}

You can also configure settings directly from the sidebar:

Open the Diff Manifests sidebar
Expand the "Settings" section
Click on any setting item to modify it:
- Python Path: Change Python executable path
- Package Path: Set custom diffmanifests installation path (shown only when Auto Install is off)
- Config File: Select default config.json file
- Output Format: Switch between JSON and Excel
- Auto Install: Toggle automatic installation
- Show Output: Toggle output panel visibility
- Open Settings: Access full extension settings

Available Commands

All commands are available via Command Palette (Ctrl+Shift+P):

Diff Manifests: Compare Two Manifest Files - Start a new comparison
Diff Manifests: Compare Selected Files - Compare from selected file
Diff Manifests: Open Output File - Open a result file
Diff Manifests: Check Environment - Verify Python and package installation
Refresh (Sidebar) - Refresh the sidebar view
Open Settings - Open extension settings
Configure Python Path - Set Python executable path
Configure Config File - Set default config file
Configure Output Format - Choose output format
Toggle Auto Install - Enable/disable auto-installation
Toggle Show Output Panel - Enable/disable auto-show output
Clear Recent Files - Clear recent files list

Python Package Installation

The extension requires the diffmanifests Python package. It will offer to install it automatically on first use, or you can install it manually:

Windows:

pip install diffmanifests
pip show diffmanifests  # Verify installation

Ubuntu/Linux:

pip3 install diffmanifests
# Or with --user flag if permission denied
pip3 install --user diffmanifests
pip3 show diffmanifests  # Verify installation

macOS:

pip3 install diffmanifests
pip3 show diffmanifests  # Verify installation

Platform-Specific Setup

Windows

Ensure Python is added to PATH during installation
Check "Add Python to PATH" when installing Python
Use python command by default
Use forward slashes or double backslashes in path settings

Ubuntu/Linux

Use python3 command (Python 2 may be installed as python)
Install pip if not available: sudo apt install python3-pip
Update the diffmanifests.pythonPath setting to python3
Use --user flag for pip install if permission denied

macOS

Use python3 command (similar to Linux)
Install Python 3 via Homebrew: brew install python3
Update the diffmanifests.pythonPath setting to python3

Commands

The extension provides the following commands:

Diff Manifests: Compare Two Manifest Files - Start a new comparison
Diff Manifests: Compare Selected Files - Compare using selected file
Diff Manifests: Open Output File - Open a previous output file

Config File Format

The extension requires a config.json file with Gerrit and Gitiles API configuration:

{
  "gerrit": {
    "host": "your-gerrit-host.com",
    "port": 443,
    "protocol": "https",
    "user": "your-username",
    "pass": "your-password"
  },
  "gitiles": {
    "host": "your-gitiles-host.com",
    "port": 443,
    "protocol": "https"
  }
}

Output Formats

JSON Output

Provides detailed comparison results in structured JSON format:

Project differences
Commit information
Hashtags
Change details

TXT Output

Generates a plain text file with:

Human-readable comparison results
Easy to share and view
Simple text format
No special software required

Excel Output

Creates an Excel spreadsheet with:

Summary sheet
Detailed changes per project
Easy filtering and sorting
Formatted tables

Troubleshooting

📖 For comprehensive troubleshooting, see INSTALL.md

Common Issues

Python Not Found

Windows:

# Add Python to PATH manually
# 1. Find Python installation: C:\Users\<user>\AppData\Local\Programs\Python\Python3X
# 2. Add to System Environment Variables > Path
# 3. Restart VS Code

Ubuntu/Linux:

# Use python3 instead of python
# Update extension settings to use python3
python3 --version

Package Not Installed

Windows:

pip install diffmanifests
pip show diffmanifests

Ubuntu/Linux:

pip3 install diffmanifests
# Or with --user flag if permission denied
pip3 install --user diffmanifests
pip3 show diffmanifests

Extension Not Working

Check if extension is installed:

code --list-extensions | grep diffmanifests

Reload VS Code:
- Press Ctrl+Shift+P
- Type "Reload Window"
Check the Output panel:
- View > Output
- Select "Diff Manifests" from dropdown

diffmanifests Command Not Found

Verify Python package is installed:

python -m pip show diffmanifests    # Windows
python3 -m pip show diffmanifests   # Ubuntu/Linux

Test running directly:

python -m diffmanifests --help      # Windows
python3 -m diffmanifests --help     # Ubuntu/Linux

Check the extension output panel for detailed error messages

Permission Errors

Ubuntu/Linux:

# Install with --user flag
pip3 install --user diffmanifests

# Or use virtual environment
python3 -m venv venv
source venv/bin/activate
pip install diffmanifests

Windows:

# Run as administrator or use --user flag
pip install --user diffmanifests

Output File Not Created

Check the Output panel (View > Output > Diff Manifests) for error messages
Verify config.json format is correct (see Config File Format section)
Ensure manifest files are valid XML
Check network connectivity for Gerrit/Gitiles API access
Verify output directory has write permissions

Development

Setup

cd vscode
npm install

Compile

npm run compile

Watch Mode

npm run watch

Package

npm install -g @vscode/vsce
vsce package

Additional Resources

📖 Installation Guide - Detailed platform-specific installation instructions
🚀 Quick Start Guide - Get started quickly
👨‍💻 Development Guide - For contributors and developers
📝 Changelog - Version history and updates
🔗 GitHub Repository
📦 PyPI Package
🐛 Issue Tracker

Getting Help

Detailed Installation: See INSTALL.md for step-by-step platform-specific instructions
Troubleshooting: Check INSTALL.md#troubleshooting for solutions
Quick Reference: See QUICKSTART.md for common tasks
Report Issues: Use our Issue Tracker

Uninstallation

Remove VS Code Extension:

code --uninstall-extension craftslab.diffmanifests

Remove Python Package:

pip uninstall diffmanifests    # Windows
pip3 uninstall diffmanifests   # Ubuntu/Linux

License

Apache-2.0

Contributing

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

For development setup and guidelines, see DEVELOPMENT.md.

Diff Manifests

craftslab

Diff Manifests VS Code Extension

Features

Prerequisites

Installation

Quick Install (Recommended)

Windows

Ubuntu/Linux

Installation Methods

Method 1: From VSIX File (Local Installation)

Method 2: Development Mode (For Testing)

Method 3: From VS Code Marketplace (When Published)

Post-Installation Setup

Configure Python Path

Verify Installation

Usage

Method 1: Sidebar (Recommended)

Method 2: Command Palette

Method 3: Context Menu

Method 4: Using Settings

Configuration

Example Configuration

Quick Configuration from Sidebar

Available Commands

Python Package Installation

Platform-Specific Setup

Windows

Ubuntu/Linux

macOS

Commands

Config File Format

Output Formats

JSON Output

TXT Output

Excel Output

Troubleshooting

Common Issues

Python Not Found

Package Not Installed

Extension Not Working

diffmanifests Command Not Found

Permission Errors

Output File Not Created

Development

Setup

Compile

Watch Mode

Package

Additional Resources

Getting Help

Uninstallation

License

Contributing