commitstats

Commit statistics from Bitbucket Cloud — get a per-user commit report for any workspace or repository over a date range. Uses the Bitbucket REST API; no server-side filtering by date/author exists, so this tool fetches and aggregates client-side.

Features

• Per-user commit counts for a given date range
• Single repo or entire workspace — omit --repo to scan all repositories in a workspace
• Optional branch filter — e.g. only main or develop
• Progress bars — repo progress and per-repo commit progress (powered by tqdm)
• Credentials via .env — no need to export secrets in the shell

Requirements

• Python 3.8+
• Bitbucket Cloud account with access to the workspace/repos you want to report on
• API token with at least Repository read (Bitbucket → Personal settings → API tokens)

Quick start

1. Clone the repository

git clone https://github.com/qrstuff/commitstats.git
cd commitstats

2. Create a virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Configure credentials

Copy the example env file and add your Bitbucket credentials:

cp .env.example .env

Edit .env and set:

• BITBUCKET_USER — your Bitbucket account email (not username)
• BITBUCKET_APP_PASSWORD — your API token (or create one: Personal settings → API tokens → Create token, scope: Repository read)

BITBUCKET_USER=you@example.com
BITBUCKET_APP_PASSWORD=your-api-token

Important: Never commit .env — it is listed in .gitignore. Use .env.example as a template only.

4. Run a report

All repositories in a workspace (e.g. 69 repos):

python get_commit_report.py --workspace YOUR_WORKSPACE --from 2025-01-01 --to 2025-01-31

Single repository:

python get_commit_report.py --workspace YOUR_WORKSPACE --repo my-repo --from 2025-01-01 --to 2025-01-31

Only a specific branch (e.g. main):

python get_commit_report.py --workspace YOUR_WORKSPACE --from 2025-01-01 --to 2025-01-31 --branch main

Example output

Repos: 100%|██████████| 3/3 [00:45<00:00, 15.2s/ repo]
Repo 3/3: my-repo: 1200/1200 commits [00:12, 98.3 commits/s]

Commits in 2025-01-01 .. 2025-01-31 (workspace MYWORKSPACE, branch: default): 342

User (display)                    Count
---------------------------------------------
  Alice Smith                      89
  Bob Jones                        72
  Carol Lee                        58
  ...

Options

Option	Required	Description
--workspace	Yes	Bitbucket workspace (team) slug
--repo	No	Repository slug. If omitted, all repos in the workspace are scanned
--from	Yes	Start date (YYYY-MM-DD)
--to	Yes	End date (YYYY-MM-DD)
--branch	No	Limit to a branch (e.g. main, develop)
--pagelen	No	API page size (default: 100)

Troubleshooting

• 401 Unauthorized — Check that BITBUCKET_USER is your email, that the token is valid and has Repository read, and that you have access to the workspace.
• No repositories found — Verify the workspace slug and that your account is a member (or has access) to that workspace.
• Progress bar looks wrong — Ensure tqdm is installed (pip install -r requirements.txt). The script still runs without it.

License

This project is licensed under the MIT License — see LICENSE for details.

Links

• Repository: github.com/qrstuff/commitstats
• Bitbucket Cloud REST API — Commits
• Bitbucket API tokens