A VS Code interface for the drift CLI. This extension provides visual status indicators and a summary of branch staleness compared to a remote upstream. This also supports analyzing changes across forks. If you are working on a forked repository, the drift CLI can compare your local changes against the base branch of the original upstream repository (not your personal fork's upstream). This helps you identify staleness or overlaps with the main project's development.
Important: CLI Wrapper
This extension is a UI wrapper and does not contain the detection logic itself. It executes the drift binary found in your system PATH.
Requirement: Ensure the drift CLI is installed and available on your PATH before using the extension.
Execution environment: Commands are executed in the root directory (cwd) of the first active workspace folder.
Install the Drift CLI
Run the following commands to install the drift CLI on your system:
curl -sSL https://raw.githubusercontent.com/sanjay-subramanya/drift/main/install.sh | sh
After installing the CLI and adding the parent directory of the binary to your PATH, restart VS Code.
Features
Activity Bar (left)
Access Drift via the dedicated icon in your Activity Bar.
Interactive Setup View
A clean, "Welcome View" interface where you can configure your analysis before running it.
List of files causing drift, categorized by severity.
Status Bar
Drift: Idle / Ready state.
Analyzing...: Real-time execution feedback.
Up to Date: No high-priority drift detected.
Workspace Stale: Upstream changes detected.
Drift Error: CLI or configuration failure.
How It Works
Configuration: Use the Drift Sidebar to verify or set your parameters:
Check Fork Upstream: Toggle for analyzing changes across forks (Default: False).
Upstream Repo URL: If comparing your fork against the original upstream, the URL of the original upstream repository (e.g., https://github.com/username/project.git).
Base Branch (Remote): The remote reference to be compare against (e.g., origin/main).
Generate JSON: Toggle for structured data output.
Path: If JSON is enabled, it stores the output in this file path (Default: ./drift.json).
Action: Click the Check for Upstream Changes button in the sidebar.
Review: The extension triggers the drift CLI. All results are streamed directly to the Drift Output Channel.
Extension Command
Drift: Analyze Branch Drift
Command ID: drift.run
Access Points:
The Check for Upstream Changes button in the sidebar.
The Status Bar button (bottom right).
The "Sync" icon in the Drift view title bar.
Typical Workflow
Open a Git repository in VS Code.
Navigate to the fuzzy search icon in the Activity Bar icon.
Check that the displayed settings (Base, JSON, Path) match your needs.
Click the blue Check for Upstream Changes button.
The Output Panel will automatically focus, displaying the categorized drift:
🔥 [CRITICAL]: Conflicts found in files currently being edited.
⚠️ [HIGH]: Changes in deployment or dependency files.
ℹ️ [LOW]: Minor upstream updates.
Troubleshooting
"Drift Error":
Verify that the drift CLI is installed and accessible in your system's PATH.
Check the Drift Output Channel for the specific CLI error message.
Output Channel Visibility:
If the output doesn't pop up automatically, go to View > Output and select Drift from the dropdown menu.
JSON Recorded Message:
If JSON mode is enabled, the CLI saves results to a file. The extension will report "JSON output recorded" in the channel; check your specified path for the data file.
Technical Details
Iconography:
Status updates use standard VS Code ThemeIcons for a native look and feel.
Filtering:
While the raw output prints everything, the Status Bar only turns "Warning" (Stale) if [CRITICAL] or [HIGH] items are detected.
