git-digger

Digger CLI

A program for extracting 'contribution data' from git repositories into JSON files.

Installation

You can install the tool using any NPM-like system.

Local Example

npm i -D git-digger # this will install it into a project as a dev dependency

npx digger current-contribution-data $(pwd) # You can use npx to run a project's programs easily

Global Example

npm i -g git-digger # this will install it globally into npm

digger current-contribution-data $(pwd) # Now it should be available via NPM's path on your shell.

Commands

Current Contribution Data

The current-contribution-data command will collect the most recent contribution to the repository.

The most recent contribution is calculated by looking for the most recent, non-HEAD tag, and then including every commit after that until the current HEAD.

Output

The contribution data JSON is created at ./currentContributionData.json.

It will include all fields listed here.

Any "Instant" in the specification is an ISO 8601 date-time. Any Duration is an ISO 8601 duration.

All Contribution Data

The all-contribution-data command will collect all the contributions in the git repository.

This is calculated by subdividing the repository by its tags, and each section becomes a contribution.

Output

The contribution data JSON is created at ./allContributionData.json, as a JSON array.

It will include all fields listed here.

Any "Instant" in the specification is an ISO 8601 date-time. Any Duration is an ISO 8601 duration.

Structured Output

Both commands support machine-readable JSON output for CI/CD pipelines and automation scripts via the --format flag.

Format Options

• --format=text (default): Writes JSON to a file and prints a confirmation message
• --format=json: Outputs structured JSON to stdout wrapped in a status envelope

Text Mode (Default)

Example command:

digger current-contribution-data $(pwd)

Output:

Data written to currentContributionData.json

The JSON data is written to currentContributionData.json (or the file specified by --output-file).

JSON Mode

Example command:

digger current-contribution-data $(pwd) --format=json

Success response:

{
  "status": "success",
  "data": {
    "storyId": "STORY-123",
    "contributors": [
      {
        "email": "[e-mail]",
        "name": "John Doe"
      }
    ],
    "commits": [
      {
        "sha": "abc123",
        "message": "[STORY-123] [patch] Fix bug",
        "dateTime": "2026-05-19T10:30:00Z"
      }
    ],
    "semver": "Patch",
    "label": "my-project",
    "firstCommitDateTime": "2026-05-19T10:30:00Z",
    "lastCommitDateTime": "2026-05-19T10:30:00Z",
    "ease": 3
  }
}

The data field contains the contribution data object. See ContributionDataJson.kt for the complete schema, or use current-contribution-data --help for field descriptions.

AllContributionData JSON Mode

Example command:

digger all-contribution-data $(pwd) --format=json

Success response:

{
  "status": "success",
  "data": [
    {
      "storyId": "STORY-123",
      "contributors": [],
      "commits": [],
      "semver": "Patch",
      "label": "my-project",
      "firstCommitDateTime": "2026-05-19T10:30:00Z",
      "lastCommitDateTime": "2026-05-19T10:30:00Z",
      "ease": 3
    }
  ]
}

(Additional contribution objects omitted for brevity)

The data field contains an array of contribution data objects, one for each contribution period. Use all-contribution-data --help for more details.

CI Integration Examples

Extract story ID in GitHub Actions:

- name: Get current contribution
  id: contribution
  run: |
    STORY_ID=$(digger current-contribution-data $(pwd) --format=json | jq -r '.data.storyId')
    echo "story-id=$STORY_ID" >> $GITHUB_OUTPUT

- name: Use story ID
  run: |
    echo "Current story: ${{ steps.contribution.outputs.story-id }}"

Extract contributor list in bash:

# Get contributors
CONTRIBUTORS=$(digger current-contribution-data $(pwd) --format=json | jq -r '.data.contributors[].name')

echo "Contributors:"
echo "$CONTRIBUTORS"

Check semver type:

OUTPUT=$(digger current-contribution-data $(pwd) --format=json 2>/dev/null)
SEMVER=$(echo "$OUTPUT" | jq -r '.data.semver')

case "$SEMVER" in
  "Major")
    echo "Breaking change detected"
    ;;
  "Minor")
    echo "New feature detected"
    ;;
  "Patch")
    echo "Bug fix detected"
    ;;
  "None")
    echo "No version bump"
    ;;
esac

Extract all story IDs:

# Get all contributions and extract story IDs
STORY_IDS=$(digger all-contribution-data $(pwd) --format=json | jq -r '.data[].storyId' | sort -u)

echo "All story IDs:"
echo "$STORY_IDS"

Help

For a full listing of the available options in the program, please use the built-in help command.

digger --help

For fit-assessment guidance and workflow recommendations:

digger guide

Documentation is also available as markdown files in the repository:

• Digger Guide - Fit assessment, philosophy, and workflow guidance
• Digger Help - Main command overview and options
• Current Contribution Data Help - Command details and output format
• All Contribution Data Help - Command details and output format