Metadata-Version: 2.5
Name: trueloc
Version: 0.5.0
Summary: Count lines of code from GitHub pull requests
Author-email: Bas Nijholt <bas@nijho.lt>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.12
Requires-Dist: dateparser>=1
Requires-Dist: diskcache>=5
Requires-Dist: httpx>=0.28
Requires-Dist: rich>=13
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

# trueloc - Lines of Code Counter

[![PyPI](https://img.shields.io/pypi/v/trueloc)](https://pypi.org/project/trueloc/)
[![Python](https://img.shields.io/pypi/pyversions/trueloc)](https://pypi.org/project/trueloc/)
[![License](https://img.shields.io/github/license/basnijholt/trueloc)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/trueloc)](https://pypi.org/project/trueloc/)
[![CI](https://img.shields.io/github/actions/workflow/status/basnijholt/trueloc/pytest.yml?label=tests)](https://github.com/basnijholt/trueloc/actions/workflows/pytest.yml)
[![Docs](https://img.shields.io/badge/docs-trueloc.nijho.lt-blue)](https://trueloc.nijho.lt)

<img src="https://raw.githubusercontent.com/basnijholt/trueloc/main/logo.svg" alt="trueloc Logo" align="right" style="width: 150px;" />

A CLI tool to analyze your coding activity via GitHub pull requests and direct commits:

- **Total lines** written since any date
- **Per-PR and per-commit breakdown** showing when each contribution was made
- **File type analysis** revealing which languages you've worked with most

Counts ALL lines touched across every commit in a PR—even for squash merges where GitHub only shows the final diff. For example, a PR where you add 1000 lines, delete them, then add 1 line shows +1001 / -1000 (not just +1).

## Installation

Recommended (installs in isolated environment):
```bash
uv tool install trueloc
```

Or run directly without installing:
```bash
uvx trueloc count USERNAME --since 1m
```

Alternatively, with pip:
```bash
pip install trueloc
```

Requires the GitHub CLI (`gh`) to be installed and authenticated:
```bash
gh auth login
```

## Usage

```bash
# Count lines from PRs and direct commits since a date
trueloc count USERNAME --since 2023-01-01

# Use relative dates
trueloc count USERNAME --since 5d      # 5 days ago
trueloc count USERNAME --since 2w      # 2 weeks ago
trueloc count USERNAME --since 3m      # 3 months ago
trueloc count USERNAME --since 1y      # 1 year ago
trueloc count USERNAME --since "last month"

# Specify a date range
trueloc count USERNAME --since 2024-01-01 --until 2024-06-30

# Count only net diff (not per-commit)
trueloc count USERNAME --since 2023-01-01 --net

# Exclude direct commits (PRs only)
trueloc count USERNAME --since 2023-01-01 --no-direct-commits

# Hide file extension breakdown
trueloc count USERNAME --since 2023-01-01 --no-extensions

# Disable caching (fresh API calls)
trueloc count USERNAME --since 2023-01-01 --no-cache

# Output as JSON for scripting/postprocessing
trueloc count USERNAME --since 2023-01-01 --json

# Clear the cache
trueloc clear-cache
```

## Example Output

Running `trueloc count basnijholt -s 1y` produces:

<!-- CODE:BASH:START -->
<!-- echo '```' -->
<!-- cat docs/example-output.txt -->
<!-- echo '```' -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```
                             Lines of Code by Month
┏━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Month   ┃ Additions ┃ Deletions ┃   Total ┃      Net ┃                       ┃
┡━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ 2025-01 │    +9,886 │      -933 │  10,819 │   +8,953 │                       │
│ 2025-02 │   +16,893 │    -5,776 │  22,669 │  +11,117 │                       │
│ 2025-03 │   +74,655 │   -30,098 │ 104,753 │  +44,557 │ ███                   │
│ 2025-04 │   +27,380 │    -7,696 │  35,076 │  +19,684 │ █                     │
│ 2025-05 │   +14,356 │    -3,983 │  18,339 │  +10,373 │                       │
│ 2025-06 │   +42,728 │   -17,681 │  60,409 │  +25,047 │ █                     │
│ 2025-07 │  +163,684 │   -93,242 │ 256,926 │  +70,442 │ ████████              │
│ 2025-08 │   +49,019 │   -15,727 │  64,746 │  +33,292 │ ██                    │
│ 2025-09 │   +13,597 │      -834 │  14,431 │  +12,763 │                       │
│ 2025-10 │  +180,196 │   -74,821 │ 255,017 │ +105,375 │ ████████              │
│ 2025-11 │  +711,228 │  -216,940 │ 928,168 │ +494,288 │ ████████████████████… │
│ 2025-12 │  +253,971 │   -72,893 │ 326,864 │ +181,078 │ ██████████            │
│ 2026-01 │  +211,498 │  -102,750 │ 314,248 │ +108,748 │ ██████████            │
└─────────┴───────────┴───────────┴─────────┴──────────┴───────────────────────┘
        Lines by Month - Top 3 Languages
┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓
┃ Month   ┃     .py ┃    .js ┃ .ipynb ┃   Total ┃
┡━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩
│ 2025-01 │     286 │  8,407 │      - │   8,693 │
│ 2025-02 │   9,560 │  8,194 │      - │  17,754 │
│ 2025-03 │  69,628 │ 18,925 │      - │  88,553 │
│ 2025-04 │   6,840 │  6,520 │      - │  13,360 │
│ 2025-05 │   3,889 │  8,874 │      - │  12,763 │
│ 2025-06 │  30,345 │  9,076 │    142 │  39,563 │
│ 2025-07 │ 102,308 │ 59,393 │  2,039 │ 163,740 │
│ 2025-08 │  47,366 │  2,140 │      - │  49,506 │
│ 2025-09 │   2,581 │  4,569 │      - │   7,150 │
│ 2025-10 │ 148,358 │  6,873 │      - │ 155,231 │
│ 2025-11 │ 212,580 │  7,348 │ 54,103 │ 274,031 │
│ 2025-12 │ 150,940 │ 18,657 │ 11,973 │ 181,570 │
│ 2026-01 │  87,307 │    162 │  6,724 │  94,193 │
└─────────┴─────────┴────────┴────────┴─────────┘
                               Commits per Month
┏━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Month   ┃ PR Commits ┃ Direct ┃ Total ┃ PRs ┃ Avg/PR ┃                      ┃
┡━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ 2025-01 │         28 │     80 │   108 │  10 │    2.8 │ █                    │
│ 2025-02 │         57 │    132 │   189 │  12 │    4.8 │ █                    │
│ 2025-03 │        446 │    529 │   975 │  77 │    5.8 │ █████████            │
│ 2025-04 │        127 │    332 │   459 │  26 │    4.9 │ ████                 │
│ 2025-05 │         14 │     96 │   110 │   6 │    2.3 │ █                    │
│ 2025-06 │         93 │    372 │   465 │  29 │    3.2 │ ████                 │
│ 2025-07 │        483 │    366 │   849 │  34 │   14.2 │ ████████             │
│ 2025-08 │        111 │    153 │   264 │  13 │    8.5 │ ██                   │
│ 2025-09 │         19 │     44 │    63 │   6 │    3.2 │                      │
│ 2025-10 │        271 │    374 │   645 │  10 │   27.1 │ ██████               │
│ 2025-11 │        871 │    638 │ 1,509 │  91 │    9.6 │ ██████████████       │
│ 2025-12 │      1,261 │    842 │ 2,103 │ 255 │    4.9 │ ████████████████████ │
│ 2026-01 │        778 │    279 │ 1,057 │ 174 │    4.5 │ ██████████           │
└─────────┴────────────┴────────┴───────┴─────┴────────┴──────────────────────┘
                      Lines of Code by Repository (Top 15)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┓
┃ Repository                 ┃ PRs ┃ Commits ┃ Additions ┃ Deletions ┃   Total ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━┩
│ agent-cli                  │ 187 │     447 │  +456,555 │  -176,185 │ 632,740 │
│ glove80                    │   3 │     171 │  +399,278 │  -101,727 │ 501,005 │
│ aijournal                  │  23 │     413 │  +226,087 │   -96,154 │ 322,241 │
│ compose-farm               │ 148 │     354 │  +104,679 │   -40,606 │ 145,285 │
│ assistant-ui-anywidget     │   3 │      68 │   +88,792 │   -45,449 │ 134,241 │
│ glove80-tailorkey-hrm-tra… │   - │      15 │   +67,317 │   -36,474 │ 103,791 │
│ home-assistant-config      │   7 │     196 │   +96,970 │    -4,133 │ 101,103 │
│ dotbins                    │  87 │     382 │   +56,921 │   -28,684 │  85,605 │
│ basnijholt                 │   1 │     182 │   +42,461 │   -39,521 │  81,982 │
│ dotfiles                   │  24 │     878 │   +35,555 │   -16,168 │  51,723 │
│ adaptive-lighting          │  22 │      30 │   +29,316 │    -4,990 │  34,306 │
│ lesdeuxchevaux             │  86 │      90 │   +20,971 │    -6,913 │  27,884 │
│ .dotbins                   │   - │     102 │   +13,378 │   -12,303 │  25,681 │
│ matty                      │   4 │      57 │   +16,119 │    -7,407 │  23,526 │
│ nijho.lt                   │  20 │     126 │   +20,356 │    -1,812 │  22,168 │
└────────────────────────────┴─────┴─────────┴───────────┴───────────┴─────────┘
                          Top 10 Contributions by Size
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Ref     ┃ Description                   ┃ Additions ┃ Deletions ┃ Date       ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ 339c987 │ glove80: Expand TailorKey     │  +164,547 │      -113 │ 2025-11-09 │
│         │ variants for all alpha ...    │           │           │            │
│ PR #224 │ agent-cli: feat(server): add  │   +47,187 │   -21,668 │ 2026-01-15 │
│         │ Whisper ASR server wit...     │           │           │            │
│ PR #88  │ agent-cli: Add memory-proxy   │   +48,172 │    -7,943 │ 2025-11-23 │
│         │ based on SOTA systems b...    │           │           │            │
│ becf3a3 │ glove80: Retire redundant     │       +77 │   -54,763 │ 2025-11-08 │
│         │ sources/variants inputs       │           │           │            │
│ 1db6c4c │ glove80: Add canonical layout │   +54,811 │        -0 │ 2025-11-08 │
│         │ sources and generat...        │           │           │            │
│ 6568292 │ glove80: Add original files   │   +54,684 │        -0 │ 2025-11-08 │
│ PR #5   │ aijournal: Data models        │   +33,791 │   -16,493 │ 2025-10-31 │
│ 47d10c6 │ glove80-tailorkey-hrm-transf… │   +34,409 │        -0 │ 2025-11-07 │
│         │ Add base/HRM layer utilities  │           │           │            │
│ 1294c50 │ glove80-tailorkey-hrm-transf… │        +0 │   -34,195 │ 2025-11-07 │
│         │ Prune intermediate layout     │           │           │            │
│         │ snapshots                     │           │           │            │
│ PR #84  │ agent-cli: feat: add proxy    │   +24,787 │    -2,305 │ 2025-11-20 │
│         │ RAG server                    │           │           │            │
└─────────┴───────────────────────────────┴───────────┴───────────┴────────────┘
           Lines by File Extension (Top 15)
┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━┓
┃ Extension ┃ Additions ┃ Deletions ┃   Total ┃     % ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━┩
│ .py       │  +639,983 │  -232,005 │ 871,988 │ 36.1% │
│ .json     │  +499,306 │  -141,866 │ 641,172 │ 26.6% │
│ .md       │  +220,367 │  -121,747 │ 342,114 │ 14.2% │
│ .js       │  +127,403 │   -31,735 │ 159,138 │  6.6% │
│ .lock     │  +115,148 │   -24,765 │ 139,913 │  5.8% │
│ .ipynb    │   +38,825 │   -36,156 │  74,981 │  3.1% │
│ .nix      │   +15,467 │    -8,490 │  23,957 │  1.0% │
│ .txt      │   +15,816 │    -2,467 │  18,283 │  0.8% │
│ .sh       │   +10,565 │    -5,801 │  16,366 │  0.7% │
│ .yaml     │   +10,415 │    -5,831 │  16,246 │  0.7% │
│ keychain  │    +7,931 │    -7,922 │  15,853 │  0.7% │
│ .html     │   +11,329 │    -3,309 │  14,638 │  0.6% │
│ .tsx      │    +7,648 │    -4,941 │  12,589 │  0.5% │
│ .yml      │   +10,001 │    -1,596 │  11,597 │  0.5% │
│ .toml     │    +7,530 │    -2,310 │   9,840 │  0.4% │
└───────────┴───────────┴───────────┴─────────┴───────┘
Activity Stats
  Average lines per contribution: 484
  Average PR size: 1,236 lines
  Most productive day: Sun
  Lines by day of week:
    Mon: ▓▓▓▓▓▓▓▓▓ 213,687
    Tue: ▓▓▓▓▓▓▓▓▓▓▓▓ 294,270
    Wed: ▓▓▓▓▓▓▓▓▓▓ 250,674
    Thu: ▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 324,756
    Fri: ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 425,349
    Sat: ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 441,004
    Sun: ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 462,725
PR Size Distribution
      <100: ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  378 ( 50.9%)
   100-500: ▓▓▓▓▓▓▓▓▓▓            194 ( 26.1%)
    500-1K: ▓▓                     52 (  7.0%)
     1K-5K: ▓▓▓                    73 (  9.8%)
       >5K: ▓▓                     46 (  6.2%)
Quality Indicators
  Documentation: 14.9% of total lines
  Test-related: ~6.9% of code lines (estimated)
  Code churn: 36.4% (643,374 deleted per 1,769,091 added)
Total PRs: 743 (per-commit totals)
Direct commits: 4237
Total additions: +1,769,091
Total deletions: -643,374
Total lines changed: 2,412,465
Cache hits: 4980
Congratulations! You've written over a million lines of code since 1y!
```

<!-- OUTPUT:END -->

## CLI Reference

### Main Commands

<!-- CODE:BASH:START -->
<!-- echo '```' -->
<!-- trueloc --help -->
<!-- echo '```' -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: trueloc [OPTIONS] COMMAND [ARGS]...

 Count lines of code from GitHub pull requests.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --install-completion            Install completion for the current shell.              │
│ --show-completion               Show completion for the current shell, to copy it or   │
│                                 customize the installation.                            │
│ --help                -h        Show this message and exit.                            │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮
│ count         Count lines of code from merged PRs and direct commits.                  │
│ clear-cache   Clear the disk cache.                                                    │
│ count-local   Count lines of code from a local git repository.                         │
╰────────────────────────────────────────────────────────────────────────────────────────╯

```

<!-- OUTPUT:END -->

### Count Command Options

<!-- CODE:BASH:START -->
<!-- echo '```' -->
<!-- trueloc count --help -->
<!-- echo '```' -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 Usage: trueloc count [OPTIONS] USERNAME

 Count lines of code from merged PRs and direct commits.

 By default, counts all lines touched across all commits in each PR,
 plus direct commits to the main branch (not from PRs).

 Example: a single PR where you add 1000 lines, delete them, then add
 1 line = +1001 / -1000 (even though the PR's net diff shows only +1).
 Additions and deletions are summed separately across all commits.

 Use --net to count only the final diff (net additions/deletions).
 Use --no-direct-commits to exclude direct commits to main branch.

╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮
│ *    username      TEXT  GitHub username [required]                                    │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ *  --since           -s                         TEXT  Start date (e.g., 5d, 2w, 3m,    │
│                                                       1y, 'last month', 2024-01-01)    │
│                                                       [required]                       │
│    --until           -u                         TEXT  End date (e.g., 1d, 'yesterday', │
│                                                       2024-12-31)                      │
│    --no-cache                                         Disable disk cache               │
│    --extensions          --no-extensions              Show breakdown by file extension │
│                                                       [default: extensions]            │
│    --per-commit          --net                        Count all lines touched per      │
│                                                       commit (default) vs net diff     │
│                                                       only                             │
│                                                       [default: per-commit]            │
│    --direct-commits      --no-direct-commits          Include direct commits to main   │
│                                                       branch (not from PRs)            │
│                                                       [default: direct-commits]        │
│    --json                                             Output results as JSON for       │
│                                                       scripting                        │
│    --local-git           --no-local-git               Clone repos with many commits    │
│                                                       and compute stats with git (far  │
│                                                       fewer API requests)              │
│                                                       [default: local-git]             │
│    --repo            -r                         TEXT  Only process a single repository │
│                                                       (e.g., 'owner/repo' or 'repo')   │
│    --help            -h                               Show this message and exit.      │
╰────────────────────────────────────────────────────────────────────────────────────────╯

```

<!-- OUTPUT:END -->

<!-- SECTION:features:START -->
## Features

- **Per-commit counting** (default): Counts every line touched in every commit (merge commits excluded)
- **Net diff mode**: Alternative mode that only counts final diff (`--net`)
- **All your repos**: Your own repos, plus every repo you contributed to (organizations, upstream projects, private repos)
- **Direct commits**: Includes commits pushed directly to main (not via PR), without double counting squash, rebase, or merge commits of PRs
- **Forks**: Counts commits in your own forks that aren't in the parent repo
- **File extension breakdown**: Shows which languages you've worked with
- **JSON output**: Machine-readable output for scripting (`--json`)
- **Disk caching**: Uses diskcache to avoid hammering the GitHub API
- **Local git stats**: Repos with many commits are cloned once and stats come from `git log --numstat`, using far fewer API requests (`--no-local-git` to disable)
- **Rate limit handling**: Automatically waits when rate limited with progress bar
- **Flexible dates**: Supports relative (`5d`, `2w`, `3m`, `1y`) and natural language (`last month`)
<!-- SECTION:features:END -->

## Caching Strategy

- **Immutable data** (cached forever): commit stats, PR commits, PR files
- **Mutable data** (1 day TTL): user repos, merged PR lists

Cache is stored in `~/.cache/trueloc/`.

<!-- SECTION:tech-stack:START -->
## Tech Stack

- Python 3.12+
- [Typer](https://typer.tiangolo.com/) - CLI framework
- [httpx](https://www.python-httpx.org/) - HTTP client
- [Rich](https://rich.readthedocs.io/) - Terminal output
- [diskcache](https://grantjenks.com/docs/diskcache/) - Persistent caching
- [dateparser](https://dateparser.readthedocs.io/) - Flexible date parsing
- [Hatch](https://hatch.pypa.io/) - Build system
- [Ruff](https://docs.astral.sh/ruff/) + [mypy](https://mypy-lang.org/) - Linting/typing
<!-- SECTION:tech-stack:END -->

## Development

```bash
# Install dev dependencies
uv sync --group dev

# Run tests
pytest

# Run linting
ruff check .
ruff format .
mypy .
```

## License

MIT
