GitFlow Guardian 🛡️
GitFlow Guardian is a lightweight, high-performance VS Code extension designed to streamline daily Git workflows. It optimizes branch management, tracks change impact before commit, eases merge conflict resolutions, enables stacking branches, and schedules proactive git hygiene summaries.
Key Features
1. Smart Branch Dashboard 📊
An organized TreeView in the sidebar activity panel that categorizes repository branches:
- Main Branches: Easy access to tracking heads (
main, master, develop).
- Features / Releases / Hotfixes: Auto-grouped by prefix regex patterns.
- Stale Branches: Flags branches without updates for over 30 days (customizable).
- Includes one-click branch checkout and branch deletion with unmerged checks.
2. Change Impact Analyzer 🔍
Provides inline CodeLens annotations above active file declarations outlining downstream impacts:
- Scans current workspace files to trace imports of the active module.
- Displays calculated impact counts (e.g.
Impacts 3 consumers & 2 test suites).
- Integrates Git blame to display the last modified author and commit time (e.g.,
Last modified by John Doe (3 days ago)).
3. Conflict Preview & Auto-Resolve ⚔️
Proactively manages standard Git merge conflict markers:
- Inline CodeLenses displayed directly above conflict zones.
- Keep Ours: Resolves the block with current branch edits.
- Keep Theirs: Resolves the block with incoming changes.
- Preview Conflict: Launches a native side-by-side diff comparison comparing current vs incoming changes.
4. Auto-Stacking & PR Helper ⛓️
- Stack new branch: Automates branching off existing branches, keeping trace of stack bases in local git configuration entries (
branch.<name>.stackbase).
- Generate PR Description: Compiles differences between current branch and stacked base. It produces a formatted Markdown document containing:
- Stack parent statistics
- Inline commit history
- File status summary (Added, Modified, Deleted)
5. Daily Git Hygiene ⏰
- Morning status summaries triggered daily at a scheduled hour (default
09:00).
- Scans for unpushed commits, stale branches, and whether main is behind remote.
- Integrates optional GitHub Personal Access Tokens to retrieve outstanding open Pull Requests.
- Offers interactive actions to view summary details or bulk prune stale branches.
Extension Settings
You can customize GitFlow Guardian under the standard settings page:
| Setting Key |
Type |
Default |
Description |
gitflow-guardian.enableChangeAnalyzer |
boolean |
true |
Enable inline Change Impact CodeLenses. |
gitflow-guardian.staleBranchThresholdDays |
integer |
30 |
Inactivity threshold before marking branches stale. |
gitflow-guardian.branchNamingPatterns |
object |
{ "feature": "^(feature/\|feat/)", "hotfix": "^(hotfix/\|fix/)", "release": "^release/" } |
Regex patterns mapping categories to branch types. |
gitflow-guardian.enableMorningSummary |
boolean |
true |
Activate morning hygiene check notifications. |
gitflow-guardian.morningSummaryTime |
string |
"09:00" |
Daily 24h format (HH:MM) to run hygiene reports. |
gitflow-guardian.githubToken |
string |
"" |
Optional GitHub token to fetch open PR stats. |
Commands
Access commands from the SCM View, Dashboard menus, or via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
GitFlow Guardian: Refresh DashboardGitFlow Guardian: Checkout BranchGitFlow Guardian: Delete BranchGitFlow Guardian: Stack New BranchGitFlow Guardian: Generate PR DescriptionGitFlow Guardian: Show Morning Summary
Developer Guide
Prerequisites
Installation
Clone this repository to your computer and navigate to the directory, then install development dependencies:
npm install
Build & Run
Compile the TypeScript code using esbuild:
- Run compile:
npm run compile
- Watch mode (automatic recompilation on changes):
npm run watch
To test the extension:
- Open this folder in VS Code.
- Press
F5 (or go to Run & Debug side view and click "Run Extension").
- A new window (Extension Development Host) opens with GitFlow Guardian activated.
Packaging
To build a production-ready package .vsix file:
- Install
vsce globally or run it via npx:
npx @vscode/vsce package
- This generates a file named
gitflow-guardian-1.0.0.vsix in the workspace root.
Publishing
Publish your extension to the VS Code Marketplace:
npx @vscode/vsce publish
(Requires a marketplace publisher account and Personal Access Token).
