Agentia Repo Doctor

A cleanup pass for a Copado Salesforce Git clone, meant to run every six months or so. It reports stale and oddly named branches, Salesforce content that bloats the repository, and git-sizer history findings. It makes only changes that leave every commit, tag, and the reflog alone, and it only prints the commands that rewrite history.

agentia repo doctor                          # report, then choose what to change
agentia repo doctor --keep dev --keep 'uat*' # branches that are environments, never reported
agentia repo doctor --stale-days 365         # what counts as a stale feature branch (default 180)
agentia repo doctor --apply --yes            # no terminal: make the recommended safe changes
agentia repo doctor --apply --yes --delete-merged-branches --json

The plugin needs no Agentia credentials. It reads only the local clone.

Capabilities at a glance

• Runs on any local Git clone, with no org access, no credentials, and no Agentia calls.
• Opens with one table of findings, worst first, each with what to do.
• Reports repository health: size, loose objects, packs, commit graph, tracked file count.
• Sorts branches into merged, unmerged, stale, oddly named, and gone-from-remote, and infers environment branches.
• Finds Salesforce bloat: reports and dashboards, large profiles, static resources, flow versions, legacy .object format, tooling files, a missing .forceignore.
• Shows size by metadata folder, and the widest folder and deepest path behind git-sizer's scores.
• Lists the largest files in history, once per file, and can install a pinned, checksum-verified git-sizer.
• Makes only safe changes: one fetch that drops remote-tracking names the remote has already deleted, an optional setting for huge working trees (feature.manyFiles), worktree prune, repack, multi-pack index, commit graph, pack-refs.
• Deletes merged local branches only when you ask, and prints the commit id of each so it can be restored.
• Offers a checklist with the recommended items pre-ticked, a "Will run" preview, and a final confirmation; Ctrl-C changes nothing.
• Prints manual steps for what it never runs: history rewrites, remote branch deletion, Git LFS, sf conversions.
• Lists branch names for scripts with --list.
• Supports --apply --yes for unattended runs and --json for machine-readable output.
• Compares HEAD, local branches, tags, and the reflog before and after, and fails the run on any unexpected difference. Remote-tracking names may change when the fetch runs.
• Never rewrites commits or tags, never deletes a branch on the remote, never runs gc or push. The only fetch is git fetch --all --prune --no-tags, and actions that need the remote share that one fetch.

What it reports

0. Findings: one short table that opens the report, worst first, each with what was found and what to do. It also holds storage (size, packs, loose objects, commit graph) and names the widest folder and deepest path behind git-sizer's scores. The sections below add detail only for what was found.

1. Repository health: loose objects, packs, size, commit graph, tracked file count.

2. Branches (local data, as fresh as your last git fetch):

   • merged feature/ branches and merged promotion/ branches
   • promotion/ branches that are not merged
   • unmerged feature/ branches with no commit for --stale-days
   • branches outside feature/ and promotion/
   • local branches whose remote branch is gone

   "Merged" means merged into the default branch or into an environment branch. Environment branches are found from promotion merges, including Copado's Merging promotion/P… into uat commits. Pass --keep for any it misses. The default branch, the checked-out branch, and --keep matches are never reported.

3. Salesforce content (read from the files at HEAD, no org access), shown only for Salesforce projects:

   • reports and dashboards (25 or more files)
   • profiles (one over 500 KiB, or 5 MiB in total)
   • object translations (1,000 or more files)
   • content assets (10 MiB or more, excluding the metadata sidecar)
   • static resources (10 MiB in total, or one over 2 MiB)
   • flow version files Name-N.flow-meta.xml (5 or more)
   • legacy .object source format
   • tracked noise such as .sfdx/, .sf/, node_modules/, .DS_Store, *.log
   • a missing .forceignore
   • size by metadata folder (with bars) and the largest files that no finding already covers

4. History findings from git-sizer, with the biggest blobs listed once per file (versions grouped). Scores are not capped at 10: 10 or more is severe. If git-sizer is missing, the plugin can install a pinned, checksum-verified copy in ~/.agentia/plugins/repo-doctor/ after you confirm. It reports the findings and does not run history rewrites.

The thresholds are heuristics, not limits Salesforce or Git enforce.

What it can change

One checklist with the recommended items ticked (space toggles an item, a toggles all), then a "Will run" line and one final confirmation (default no). The list stops at the first and last item instead of wrapping around. Each change is its own item. Ctrl-C ends the command with "Nothing was changed." and exit code 130. In a terminal the checklist replaces the Changes table. --apply --yes makes only the recommended safe changes: the fetch, worktree prune, repack, multi-pack index, commit graph, and pack-refs. Branch deletion always needs an explicit choice (--delete-merged-branches for branches).

| Situation | Change | | --- | --- | | Remote-tracking branches exist | git fetch --all --prune --no-tags (one fetch, even if more than one selected change needs it) | | 10,000 or more tracked files and feature.manyFiles is unset | git config --local feature.manyFiles true (not recommended by default; older tools may not read index v4) | | Worktree records whose folder is gone | git worktree prune | | 500 or more loose objects, or loose objects already packed | git repack -d --geometric=2 --write-midx (Git 2.34 or newer; also merges small packs when there are 10 or more, writes the multi-pack index, and keeps unreachable objects). Older Git: git repack -d, which only packs loose objects | | 4 or more packs, no multi-pack index, and no repack planned | git multi-pack-index write | | 5,000 or more objects and no commit graph | git commit-graph write --reachable --changed-paths | | 50 or more loose refs | git pack-refs --all | | --delete-merged-branches (or picked in the branch list) | git branch -d -- <branch> for local branches merged into the checked-out branch |

Settings are written to the repository's own config and only when unset. The plugin does not untrack reports or tooling files. The findings name the .forceignore or .gitignore line to add, and removing those files from history is a manual step. Branch deletion is local only. A branch Git refuses to delete is skipped and the run continues. The output prints the commit id of each deleted branch so it can be restored with git branch <name> <id>. The plugin does not run git gc, fetch, or push.

Manual maintenance

Fixes the plugin never runs, printed only for what this repository needs, as a table with Step, Command and Why. Steps that change history are marked [rewrites history]. The set can include deleting a remote branch (the branches section shows a few merged names; the plugin never deletes them), Git LFS and git filter-repo for large files, sparse checkout, and sf commands for converting to source format. Commands keep <placeholders> instead of names from your repository. A note below the table says that steps marked [rewrites history] replace old commits, so anyone who already has a copy has to clone again.

After applying, HEAD, all refs (except the branches you chose to delete), and the reflog are compared with the values from before. A difference fails the run.

Security

• Runs only git and git-sizer, with fixed argument lists, not a shell command.
• Does not use Agentia credentials. The only download is git-sizer, after you confirm, checked against a pinned checksum.
• Deletes a branch only when its name is a normal Git branch name. --keep accepts only * and ? patterns.

Local development

npm install && npm test
agentia plugins link . --no-install
agentia repo doctor --path .