Commit Diary VS Code Extension
Track, categorize, and explain your Git work with clarity: auto-sync, badges, and actionable insights for developers and teams.
Open the configured CommitDiary dashboard for documentation and badge setup.
Replace YOUR_USERNAME with your actual Commit Diary username.
🚀 Features
- Automatic Commit Tracking: Commits are tracked as you work, no manual steps required.
- Real-Time Cloud Sync: New commits are synced to the cloud instantly (on commit) and on a schedule (hourly/daily).
- Shareable Badge: Show off your progress and streaks with a dynamic SVG badge for your README, portfolio, or dashboard.
- Privacy Focused: CommitDiary never uploads the whole repository. Authenticated cloud reports use commit metadata plus bounded diff statistics and sampled patch excerpts.
- Offline Support: Commits are queued and synced automatically when you’re back online.
- Productivity Metrics: View commit stats, trends, and breakdowns in VS Code and on the dashboard.
🔁 Package Flow
flowchart LR
A[Git repo] --> B[Extension]
B --> C[Core: parse + categorize]
B --> D[Local DB]
B --> E[API Server]
E --> F[Web Dashboard]
E --> G[Stepper AI]
✨ Why Commit Diary?
Commit Diary helps developers understand, explain, and track their work, not just record it.
While Git tools are great at showing what changed, they often fall short when it comes to answering:
What did I actually work on?
Why does it matter?
How do I explain this clearly to others?
Commit Diary bridges that gap by turning raw Git commit history into meaningful, human-readable insights.
🚧 The Problem with Traditional Git Insights
- Git commit history is chronological, not contextual
- GitHub contribution graphs show how much you worked, not what you worked on
- GitLens provides deep file-level history, but can feel too granular for progress reporting
- Developers still spend time manually summarizing work for standups, reports, and reviews
💡 What Makes Commit Diary Different
🧠 Work-centric insights
- Categorizes commits by intent (feature, fix, refactor, docs, config, etc.)
- Detects components and code areas based on file paths
- Surfaces what changed and why, not just diffs
📊 Metrics that tell a story
- Daily, weekly, monthly, and yearly summaries
- Commit breakdowns by category and component
- Clear productivity patterns without noise or surveillance
✍️ Built for communication
- Designed to help you explain your work clearly
- Ideal for daily standups, weekly reports, retrospectives, and self-reviews
- Outputs human-readable summaries instead of raw Git logs
🔒 Local-first & privacy-respecting
- Commit analysis runs locally by default
- Cloud sync is optional and fully user-controlled
- No background tracking, no forced uploads
| Tool |
Primary Focus |
| GitHub Graph |
Activity volume |
| GitLens |
Deep code history & blame |
| Commit Diary |
Work summary & progress narrative |
Commit Diary doesn’t replace GitLens or GitHub; it sits above them, transforming low-level Git data into high-level insight.
🎯 When Commit Diary Shines
- Daily standups and async updates
- Weekly or monthly progress reports
- Tracking refactors, configs, and technical debt
- Showing real impact beyond commit counts
- Personal progress tracking across multiple projects
Commit Diary is about clarity, not clutter.
It helps developers tell the story behind their code, simply, honestly, and effectively.
🛠️ Getting Started (Initial Setup)
Install the Extension
- Search for
Commit Diary in the VS Code Marketplace and install.
Register on the Dashboard
- Open the CommitDiary dashboard configured for your environment.
- Sign up with GitHub/Google and generate your API Key from your profile/settings.
Enter Your API Key in VS Code
- Open VS Code settings (
Ctrl+, or Cmd+,).
- Search for
CommitDiary: Api Key and paste your API key.
- Or run the command:
CommitDiary: Setup Cloud Sync from the Command Palette (Ctrl+Shift+P).
That’s It!
- The extension will automatically scan your workspace for Git repositories, track your commits, and sync them to the cloud.
- No manual sync is needed; everything is automatic.
🧩 Standalone Local Development
Prerequisites
- Node.js 18+
- pnpm
- A local API running at http://localhost:3001
Install & Build
cd packages/extension
pnpm install
pnpm build
Run in VS Code (Dev)
- Open the repo in VS Code
- Launch the extension via the VS Code Run and Debug panel
- Use the command palette to run CommitDiary commands
✅ Why This Setup Works
- Extension runs locally and uses the API key to authenticate sync
- Core library provides consistent categorization across clients
- API centralizes storage, metrics, and AI report generation
🔗 How It Connects to CommitDiary
🔄 How Sync Works
- Auto-Sync on New Commits: As soon as you make a new commit, the extension detects it and syncs it to the cloud (if your API key is set).
- Scheduled Sync: In addition to real-time sync, the extension runs a scheduled sync (hourly/daily) to ensure nothing is missed.
- Offline Mode: If you’re offline, commits are queued and synced when you reconnect.
- Bounded Commit Evidence: Diff statistics and secret-redacted patch excerpts are sampled across changed files, then capped before local storage and upload.
- No Manual Triggers Needed: After initial setup, everything is background and automatic.
🧑💻 Common Commands
CommitDiary: Show My Commits: View your recent commits in VS Code.CommitDiary: Setup Cloud Sync: Enter or update your API key.CommitDiary: Show Commit Metrics: View productivity metrics and trends.CommitDiary: Discover Repositories: Scan your workspace for Git repositories.CommitDiary: Sync Now: Manually trigger a sync (rarely needed).CommitDiary: Force Full Resync: Reset sync status and re-sync all commits.CommitDiary: Export DB: Export your local commit database.
⚙️ Key Settings
commitDiary.apiKey: Your personal API key for cloud sync (required).commitDiary.autoSync.onDetection: Enable/disable auto-sync when new commits are detected (default: true).commitDiary.sync.autoInterval: Set scheduled auto-sync interval (hourly, daily).commitDiary.sync.includeEmails: Include author emails in sync (default: false).commitDiary.user.emails: Additional emails to match your commits (optional).
Before packaging a release, set COMMITDIARY_API_URL and COMMITDIARY_APP_URL in the build environment. The bundle script validates and injects these public HTTPS origins into the published extension; source files contain no deployment URL. COMMITDIARY_API_URL also remains an environment fallback for local, unbundled development.
Stable releases are published by pushing a tag matching the manifest version,
for example extension-v0.0.7. The publish workflow validates that the tag and
package.json agree before uploading to the Marketplace. Configure the
repository secret VSCE_PAT with a Marketplace publishing token.
VS Code installs Marketplace updates automatically after its configured delay,
which is two hours by default. Set extensions.autoUpdateDelay to 0 to install
updates as soon as VS Code finds them. This setting affects every extension.
Installing a local .vsix disables automatic updates for that installation by
default; reinstall from the Marketplace or enable Auto Update for CommitDiary.
For a local bundled build, use the localhost origins explicitly:
COMMITDIARY_API_URL=http://localhost:3001 \
COMMITDIARY_APP_URL=http://localhost:3000 \
pnpm bundle:dev
Local HTTP origins are accepted only by bundle:dev; release packaging remains HTTPS-only.
🆘 Troubleshooting & Help
🏅 Shareable Badge SVG
Show off your progress and consistency with a dynamic badge! Commit Diary generates a shareable SVG badge that you can embed in your README, portfolio, or personal site.
Why is this useful?
- Instantly showcase your recent activity and commitment streaks.
- Great for resumes, GitHub profiles, and team dashboards.
- Visual motivation and accountability for yourself and your team.
📲 Upcoming: Scheduled Reports to WhatsApp & Slack
Stay updated on your work without opening the dashboard. Soon, Commit Diary will let you receive:
- Short, human-readable work summaries delivered to WhatsApp or Slack
- Scheduled digests (daily, weekly, or custom)
- Shareable snippets for standups, reviews, or personal tracking
Why is this useful?
- Get a quick snapshot of your progress, even on the go
- No need to check the web dashboard for updates
- Perfect for async teams, remote work, and personal productivity
Watch this space for updates and join our community to help shape these features!
License
ISC
