CommitPulse - Git Analytics for VS Code

This is a public open-source repository. CommitPulse is a VS Code extension that provides Git commit analytics, linking commits to Jira and Linear issues, extracting code complexity metrics, and visualizing team contributions over time.

Related Projects

• CommitPulse Sync - The public repo for the https://marketplace.visualstudio.com/items?itemName=ImproviseLabs.gitr VS Code extension.

Step-by-step guide for installing, configuring, and using the CommitPulse VS Code extension (v0.1.0).

Prerequisites

Verify the following are installed before proceeding:

Docker is required — the PostgreSQL database runs in a Docker container.

scc (Sloc Cloc and Code) is optional but recommended. When available, the pipeline extracts per-file code metrics — total lines, code lines, comment lines, cyclomatic complexity, and weighted complexity — and stores them in the commit_files table. Without scc, the pipeline runs normally but these columns remain zero.

Install scc via one of:

go install github.com/boyter/scc/v3@latest   # Go
brew install scc                               # macOS
snap install scc                               # Linux (snap)

Initial Setup

Step 1: Start the Database

The CommitPulse database runs in a Docker container using PostgreSQL 16. First, ensure Docker Desktop is running, then clone the repository and start the database.

1. Clone the CommitPulse repository:

   git clone https://github.com/antonajp/CommitPulse.git
   

2. Navigate to the repository directory:

   cd CommitPulse
   

3. Start the PostgreSQL container:

   docker compose up -d
   

   This pulls the postgres:16-alpine image, creates a container named gitrx-postgres, exposes PostgreSQL on port 5433, and runs all migrations automatically on first startup.

4. Verify the container is running:

   docker ps
   

   You should see gitrx-postgres listed with status Up.

Note: The Gitr: Start Database and Gitr: Stop Database commands are registered but not yet implemented. Use docker compose up -d and docker compose down from the terminal.

Step 2: Install the Extension

1. Open VS Code
2. Click the Extensions icon in the Activity Bar (or press Ctrl+Shift+X / Cmd+Shift+X)
3. Search for CommitPulse
4. Click Install

Step 3: Set Database Password

The extension needs the database password to connect. The default password is gitrx_local_dev.

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type Gitr: Set Database Password and select it
3. Enter gitrx_local_dev (or your custom password if you changed it)

The password is stored securely in VS Code's encrypted SecretStorage.

Step 4: Configure Repositories

Open VS Code settings (Ctrl+, / Cmd+,) and add your repositories:

"gitrx.repositories": [
  {
    "path": "/home/user/repos/my-app",
    "name": "My App",
    "organization": "Engineering",
    "trackerType": "jira"
  }
]

Each repository must specify:

• path — Absolute path to the Git repository root
• name — Display name used in TreeViews and reports

Optional:

• organization — Organization or team label
• trackerType — "jira" (default), "linear", or "none"
• startDate — Earliest commit date to extract (YYYY-MM-DD). See Step 4.1 below.

See SETTINGS.md for full details and examples.

Step 4.1: Control Git History Extraction Scope (Recommended)

For repositories with extensive history (5+ years), limiting the extraction scope is highly recommended. This dramatically improves initial pipeline performance and avoids loading commits that predate your issue tracker adoption.

Option A: Global cutoff date — Apply the same cutoff to all repositories:

"gitrx.pipeline.sinceDate": "2022-01-01"

Option B: Per-repository startDate — Different cutoffs for each repo:

"gitrx.repositories": [
  {
    "path": "/home/user/repos/legacy-monolith",
    "name": "Legacy Monolith",
    "startDate": "2020-01-01"
  },
  {
    "path": "/home/user/repos/new-service",
    "name": "New Service",
    "startDate": "2024-01-01"
  }
]

Priority: Per-repo startDate takes precedence over the global sinceDate. When both are set, the later date is used for that repository.

Why this matters: A repository with 15 years of history might have 50,000+ commits. Without a cutoff, the initial pipeline run extracts all of them — which can take 30+ minutes and fills the database with commits that will never link to any issue. Setting startDate to when your organization adopted Jira/Linear reduces this to seconds.

Step 5: Choose Your Tracker Type

Each repository is configured with exactly one issue tracker. The trackerType field determines which tracker is used for commit-issue linking.

You cannot use both Jira and Linear for the same repository. If your organization is migrating from Jira to Linear, configure older repos as "jira" and newer repos as "linear".

Step 6: Set Up Additional Credentials

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run these commands to store credentials securely:

For Jira repositories:

• Gitr: Set Jira API Token — Generate at Atlassian API Tokens

For Linear repositories:

• Gitr: Set Linear API Token — Generate at Linear > Settings > API > Personal API keys. The key must start with lin_api_.

  1. Open VS Code
  2. Press Ctrl+Shift+P to open the Command Palette
  3. Type "Gitr: Set Linear API Token" and select it
  4. Paste your Linear API key in the password-masked input box

For GitHub contributor sync:

• Gitr: Set GitHub Token — GitHub PAT with read:org and read:user scopes

  1. Open VS Code
  2. Press Ctrl+Shift+P again
  3. Type "Gitr: Set GitHub Token" and select it
  4. Paste your GitHub PAT in the password-masked input box

All credentials are stored in VS Code's encrypted SecretStorage — never in settings.json or plaintext files.

Step 7: Configure Jira (if applicable)

If any repositories use trackerType: "jira", configure the Jira connection:

"gitrx.jira.server": "https://yourorg.atlassian.net",
"gitrx.jira.username": "developer@yourorg.com",
"gitrx.jira.projectKeys": ["PROJ", "FEAT", "BUG"]

Optional Jira settings:

• gitrx.jira.keyAliases — Map renamed project keys (e.g., {"PROJ": "PROJ2"})
• gitrx.jira.pointsField — Custom field ID for story points (default: customfield_10034)

See SETTINGS.md for all Jira settings.

Step 8: Configure Linear (if applicable)

If any repositories use trackerType: "linear", configure Linear:

"gitrx.linear.teamKeys": ["ENG", "PLAT"]

Optional Linear settings:

• gitrx.linear.keyAliases — Map renamed team keys
• gitrx.linear.increment — Issues to scan per incremental run (default: 200)
• gitrx.linear.daysAgo — Days to look back for unfinished issues (default: 2)

See SETTINGS.md for all Linear settings.

Data Model Overview

The pipeline processes data through a sequence of extraction, loading, linking, and analysis steps:

Git Repositories
    │
    ▼
┌──────────────────┐      ┌──────────────────┐
│ Commit Extraction │      │ GitHub Contributor│
│ (git log parsing) │      │    Sync          │
└────────┬─────────┘      └────────┬─────────┘
         │                         │
         ▼                         ▼
┌──────────────────┐      ┌──────────────────┐
│  commit_history   │      │commit_contributors│
│  commit_files     │      └──────────────────┘
│  commit_directory │
│  commit_tags      │
└────────┬─────────┘
         │
    ┌────┴────────────────────────┐
    │                             │
    ▼                             ▼
┌──────────────┐         ┌───────────────┐
│ Jira Issues  │         │ Linear Issues │
│ (API loading)│         │ (API loading) │
└──────┬───────┘         └───────┬───────┘
       │                         │
       ▼                         ▼
┌──────────────┐         ┌───────────────┐
│ jira_detail   │         │ linear_detail  │
│ jira_history  │         │ linear_history │
└──────┬───────┘         └───────┬───────┘
       │                         │
       ▼                         ▼
┌──────────────┐         ┌───────────────┐
│ commit_jira   │         │ commit_linear  │
│ (regex link)  │         │ (regex link)   │
└──────┬───────┘         └───────┬───────┘
       │                         │
       └─────────┬───────────────┘
                 │
                 ▼
        ┌────────────────┐
        │ Team Assignment │
        │ (most-frequent  │
        │  issue prefix)  │
        └────────────────┘

Database tables (23 tables, 9 views, across 4 migrations):

• Commit Analysis: commit_history, commit_files, commit_files_types, commit_directory, commit_branch_relationship, commit_tags, commit_msg_words
• Jira Integration: jira_detail, jira_history, jira_issue_link, jira_parent, jira_github_branch, jira_github_pullrequest
• Jira Linkage: commit_jira
• Linear Integration: linear_detail, linear_history
• Linear Linkage: commit_linear
• Contributors/Teams: commit_contributors, gitja_team_contributor
• Pipeline Audit: gitr_pipeline_run, gitr_pipeline_log, gitr_pipeline_sha, gitr_pipeline_jira, gitr_pipeline_linear, gitja_pipeline_table_counts

Running the Pipeline

Manual Full Run

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run Gitr: Run Pipeline
3. A progress notification shows each step as it executes
4. Results are logged to the Gitr output channel (View > Output > Gitr)

The pipeline executes 9 steps in order:

Tracker-aware behavior: Jira steps (3–5) run for repositories with trackerType: "jira". Linear steps (6–8) run for repositories with trackerType: "linear". If a tracker is not configured, its steps are gracefully skipped with an informational message.

Selective Steps

To run only specific steps, configure gitrx.pipeline.steps:

"gitrx.pipeline.steps": ["gitCommitExtraction", "commitJiraLinking"]

The default runs 5 core Jira steps. Set to [] (empty array) to run all 9 steps. See SETTINGS.md for the full step list and dependency chain.

Scheduled Pipeline

Enable automatic pipeline execution:

"gitrx.schedule.enabled": true,
"gitrx.schedule.cronExpression": "0 9 * * 1-5"

Or toggle via the Gitr: Toggle Scheduled Pipeline command. The schedule status appears in the VS Code status bar.

See SETTINGS.md for cron expression examples.

Docker Database Operations

Since the database start/stop commands are not yet implemented, manage the Docker container directly:

The database uses a named volume (gitrx-pgdata) for data persistence. Running docker compose down preserves data; docker compose down -v removes all data.

Migrations are applied automatically on first container startup via the init script at docker/init/01_run_migrations.sh.

TreeViews

The CommitPulse sidebar panel (click the Gitr icon in the Activity Bar) contains 4 TreeViews:

Repositories

Displays all configured repositories from gitrx.repositories with statistics. Each repository shows a tracker badge indicating its tracker type (Jira, Linear, or None).

Context menu actions (right-click):

• Run Pipeline for Repo — Run the pipeline for the selected repository
• Open in Terminal — Open a terminal at the repository path

Refresh: Click the refresh icon in the TreeView title bar, or run Gitr: Refresh Repositories.

Repo Stats

Displays configured repositories with commit count, branch count, and other statistics loaded from the database.

Contributors

Displays contributors grouped by team, with commit counts.

View modes (toggle via title bar icon):

• Grouped — Contributors nested under team nodes
• Flat — All contributors in a single list

Click a contributor to see their details in the Gitr output channel.

Refresh: Click the refresh icon or run Gitr: Refresh Contributors.

Pipeline Runs

Displays recent pipeline run history with status, duration, and step counts.

Click a pipeline run to view its detailed log entries in the Gitr output channel.

Refresh: Click the refresh icon or run Gitr: Refresh Pipeline Runs.

Webview Panels

Metrics Dashboard

Open via Command Palette: Gitr: Open Metrics Dashboard

Displays interactive Chart.js visualizations of:

• Commit trends over time
• Team contributions breakdown
• Technology stack distribution
• Code complexity metrics

Issue Linkage

Open via Command Palette: Gitr: Open Issue Linkage

Displays a searchable, sortable table showing which commits are linked to which issues. The panel title dynamically reflects the active tracker types — showing "Commit-Jira Linkage", "Commit-Linear Linkage", or both depending on your repository configurations.

Commands Reference

All 18 commands available in the Command Palette:

Troubleshooting

Database Connection Failures

Symptom: Pipeline fails with "connection refused" or "ECONNREFUSED".

Solutions:

1. Verify the container is running: docker compose ps
2. Check container health: docker compose logs postgres
3. Verify port is correct — default is 5433, not 5432
4. Ensure gitrx.database.port in VS Code settings matches DB_PORT in .env
5. Check for port conflicts: lsof -i :5433 or ss -tlnp | grep 5433

Port Conflicts

Symptom: docker compose up fails with "port is already allocated".

Solutions:

1. Change DB_PORT in .env to an unused port (e.g., 5434)
2. Update gitrx.database.port in VS Code settings to match
3. Stop the conflicting service: docker compose down (if another instance)

Empty Dashboards

Symptom: Metrics Dashboard or Issue Linkage shows no data.

Solutions:

1. Run the pipeline first: Gitr: Run Pipeline
2. Check the Gitr output channel for errors during pipeline execution
3. Verify repositories are configured in gitrx.repositories
4. Verify database connectivity by checking docker compose ps shows healthy

Jira API Errors

Symptom: jiraIssueLoading or jiraChangelogUpdate step fails.

Solutions:

1. Verify Jira server URL: gitrx.jira.server must include https://
2. Re-enter Jira token: Gitr: Set Jira API Token
3. Verify your Jira username (email) is correct
4. Check project keys exist in your Jira instance
5. Test connectivity: curl -u user@email:token https://yourorg.atlassian.net/rest/api/3/myself

Linear API Errors

Symptom: linearIssueLoading or linearChangelogUpdate step fails.

Solutions:

1. Re-enter Linear API key: Gitr: Set Linear API Token — key must start with lin_api_
2. Verify team keys exist in your Linear workspace
3. Check Linear API rate limits — the @linear/sdk uses GraphQL, which has a separate rate limit from the REST API
4. Set log level to DEBUG to see detailed API interaction logs

Linear API Key Missing

Symptom: Linear steps skip with "Linear not configured".

Solutions:

1. Run Gitr: Set Linear API Token from the Command Palette
2. Verify at least one repository has trackerType: "linear"
3. Verify gitrx.linear.teamKeys contains your team key(s)

Rate Limiting

Symptom: API steps fail intermittently with 429 errors or "rate limit exceeded".

Solutions:

1. Reduce gitrx.jira.increment or gitrx.linear.increment for smaller batches
2. Increase gitrx.schedule.cronExpression interval to reduce frequency
3. Check your API tier's rate limits (Jira Cloud: 100 req/min, Linear: 1500 complexity points/hour)

Pipeline Partially Succeeds

Symptom: Some steps succeed, others fail — pipeline status shows PARTIAL.

Solutions:

1. Check the Gitr output channel for error details on failed steps
2. Each step runs independently — a failure in one step does not block others
3. Fix the root cause and re-run the pipeline
4. Use selective steps to re-run only the failed step:

   "gitrx.pipeline.steps": ["jiraIssueLoading"]
   

Further Reference

• SETTINGS.md — Complete settings reference with all 24 settings
• OVERVIEW.md — Extension overview and feature highlights