nightowls 1.0.0

Analyze Git commit activity by hour with member mapping and configurable outputs.

NightOwls

NightOwls is a Python CLI for analyzing Git commit activity by hour of day.

It supports:

• JSON analysis output
• stacked bar chart PNG output (x: hour, y: commit count, stacked by member)
• resolved config output
• bootstrapped members map output

Install

python -m pip install .

For development:

python -m pip install -r requirements.txt

Run

PYTHONPATH=src python -m nightowls --help

Or after install:

nightowls --help

Configuration Sources And Precedence

NightOwls merges configuration in this order:

1. CLI options
2. -c /path/to/config.json
3. nightowls.json in repository root
4. internal defaults

JSON Schema

Schema file in repo:

• src/nightowls/schemas/nightowls.schema.json

Raw URL (for $schema):

• https://raw.githubusercontent.com/5cover/nightowls/main/src/nightowls/schemas/nightowls.schema.json

Example header in nightowls.json:

{
  "$schema": "https://raw.githubusercontent.com/5cover/nightowls/main/src/nightowls/schemas/nightowls.schema.json"
}

nightowls.json Format

{
  "$schema": "https://raw.githubusercontent.com/5cover/nightowls/main/src/nightowls/schemas/nightowls.schema.json",
  "timezone": "local",
  "identity_source": "author",
  "member_sort": "commit_count",
  "output": {
    "format": "json",
    "path": null
  },
  "chart": {
    "title": null
  },
  "filters": {
    "since": null,
    "until": null,
    "branch": null,
    "no_merges": false
  },
  "members": [
    ["Raphael", { "name": "Scover", "email": "[e-mail]" }],
    ["Romain", { "name": "Soladoc" }],
    ["Noreply", { "email": { "regex": "@users\\.noreply\\.github\\.com$" } }],
    ["Unknown", {}]
  ]
}

Members Mapping Semantics

members is an ordered list of pairs:

[member_name, matcher]

Rules:

• first match wins
• matcher.name and matcher.email are optional
• missing or null means wildcard for that field
• string value means exact match
• { "regex": "..." } means regex match
• if nothing matches, NightOwls falls back to the git actor name

Member Ordering

member_sort controls member order in JSON output and chart stacking/color assignment.

• "commit_count" (default): descending by total commit count, then alphabetical
• "alphabetical": ascending by member name
• ["name1", "name2", ...]: custom order; members not listed are appended alphabetically

Chart Title Behavior

• If chart.title (or --chart-title) is set, it is used.
• Otherwise title is Commits by hour (stacked by member) - {repo name} when repo name is available.
• Final fallback is Commits by hour (stacked by member).

CLI Options

nightowls [path]
  -c, --config PATH
  --timezone {local,utc}
  --output-format {json,png,config,members}
  --output-path PATH
  --chart-title TEXT
  --identity-source {author,committer}
  --since EXPR
  --until EXPR
  --branch REV
  --no-merges

Examples

JSON output:

nightowls . --output-format json

PNG output:

nightowls . --output-format png --output-path out.png

PNG output with custom title:

nightowls . --output-format png --chart-title "Night activity overview"

Resolved config output:

nightowls . --output-format config

Bootstrap members map:

nightowls . --output-format members > members.json

Use custom config:

nightowls . -c ./nightowls.json --output-format json

Build

python -m build

Publish To PyPI

• The Publish workflow runs on tags matching v* (for example v1.0.1).
• Configure PyPI Trusted Publishing for this repository, then create and push a version tag:

git tag v1.0.1
git push origin v1.0.1

Test

PYTHONPATH=src python -m unittest discover -s tests -p 'test_*.py'