CommitKit CLI

Automatically track your git commits and build insights into your development activity.

Installation

npm install -g commitkit

Quick Start

1. Get your API token from your CommitKit dashboard

2. Configure the CLI with your API token:

commitkit config YOUR_API_TOKEN

3. Initialize in your git repository:

cd your-project
commitkit init

4. Start coding! Your commits will now be automatically tracked.

Commands

commitkit config <api-token>

Configure your CommitKit API token. This stores your credentials securely in ~/.commitkit/config.json.

Options:

• -u, --url <url> - Set a custom API URL (default: https://commitkit.dev)

Example:

commitkit config abc123def456
commitkit config abc123def456 --url https://api.commitkit.dev

commitkit init

Initialize CommitKit in the current git repository. This installs a post-commit hook that automatically tracks your commits.

Example:

cd my-project
commitkit init

commitkit status

Show your current configuration and connection status.

Example:

commitkit status

commitkit uninstall

Remove the CommitKit hook from the current repository. Your configuration and API token remain saved.

Example:

commitkit uninstall

commitkit sync

Sync historical commits from your git repository to CommitKit. This is useful for uploading existing commits after installing CommitKit.

Basic Usage:

commitkit sync                    # Sync from default branch, skip merges
commitkit sync --dry-run          # Preview what would be synced

Date Range Options:

commitkit sync --since "2024-01-01"              # Commits since Jan 1, 2024
commitkit sync --until "1 week ago"              # All stable commits (exclude recent)
commitkit sync --since "2024-01-01" --until "2024-10-31"  # Specific date range
commitkit sync --last 100                        # Last 100 commits only

Branch Options:

commitkit sync                    # Default branch (set during init)
commitkit sync --branch main      # Specific branch
commitkit sync --all              # All branches

Note: Cannot use --branch and --all together

Merge Commit Options:

commitkit sync                    # Skip merge commits (default)
commitkit sync --include-merges   # Include merge commits

Advanced Examples:

# Sync last year's stable commits from main branch
commitkit sync --since "1 year ago" --until "1 month ago" --branch main

# Sync all commits from all branches, including merges
commitkit sync --all --include-merges

# Preview before syncing
commitkit sync --since "2024-01-01" --dry-run

# Full resync (delete and re-upload all commits)
commitkit sync --delete-all-and-resync

Options:

• --since <date> - Only sync commits since this date (inclusive)
• --until <date> - Only sync commits until this date (inclusive)
• --last <number> - Only sync last N commits
• --branch <name> - Only sync from specified branch
• --all - Include commits from all branches
• --include-merges - Include merge commits (skipped by default)
• --dry-run - Show what would be synced without actually syncing
• --delete-all-and-resync - Delete all existing commits and re-sync from scratch

How It Works

1. When you run commitkit init, a post-commit git hook is installed in your repository
2. Every time you make a commit, the hook automatically sends commit metadata to CommitKit
3. View all your tracked commits on your CommitKit dashboard
4. Your actual code is never sent - only commit metadata (hash, message, author, timestamp)

Privacy & Security

• Your API token is stored locally in ~/.commitkit/config.json
• Only commit metadata is tracked (hash, message, author, timestamp)
• Your actual code content is never accessed or transmitted
• All API communication uses HTTPS

Development

Local Testing

# Install dependencies
npm install

# Test the CLI
node index.js --help

# Configure with test token
node index.js config your-test-token

# Test in a git repo
cd /path/to/git/repo
node /path/to/commitkit-cli/index.js init

Running Tests

Unit Tests

Run the unit test suite (fast, no external dependencies):

npm test

End-to-End Tests

E2E tests verify the full stack: CLI → HTTP → Rails API → Database

Prerequisites:

1. Rails test server must be running
2. Test database must be prepared

Steps to run E2E tests:

# Terminal 1: Start Rails test server
cd ../commitkit
RAILS_ENV=test bin/rails db:test:prepare
RAILS_ENV=test bin/rails server -p 3001

# Terminal 2: Run E2E tests
cd commitkit-cli
RUN_E2E=true npm test

What E2E tests verify:

• Creates real git repository with commits
• Runs actual CLI commands as subprocess
• Makes HTTP requests to test Rails API
• Verifies commits appear in database
• Tests duplicate detection on subsequent syncs

Troubleshooting

Hook not triggering

Make sure the hook is installed:

commitkit status

Check if the hook file exists:

ls -la .git/hooks/post-commit

API connection errors

Test your connection:

commitkit status

Verify your API token on the dashboard.

Reinstalling the hook

commitkit uninstall
commitkit init

License

MIT

Links

• Website
• Dashboard
• GitHub