Contents

Discover Enterprise

Every rollout starts with gitta discover. It reads your repositories on your own machines and replays the last months of merges the way gitta checks them. You get one report with the numbers from your own history, and a plan for where to start.

Run it

Give it local repositories or repository addresses. With no path it reads the repository you are in.

Terminal

$ gitta discover ~/src/core-api ~/src/web --since 6m --out discover-report
discover: [1/2] ~/src/core-api
discover: inventory
discover: shared-code map
discover: core-api: 212 pieces of work merged, 340 overlapping pairs, replaying 340
discover: core-api: pair 41/340 #1182 + #1190: gitta warns (22 min left)
...
discover: done: discover-report/report.html

Open report.html in any browser. It needs no network, it follows the light or dark setting of your computer, and it prints cleanly. The same data is in report.json, pairs.csv, shared-code.csv and inventory.csv.

What stays on your machines

gitta discover never writes to the repositories it reads. It copies each one into a work folder inside --out and does all its work in that copy. A local repository is copied with git clone --no-local, so the copy has its own files and the original stays exactly as it was. Your code and the report stay on the machine that runs the command. It asks no questions, opens no web page and sends nothing to gitta.

What the report shows

Section	Content
Inventory	Each repository with its size, languages, commits and active contributors in the period, and the coding agents seen in commit trailers, authors and branch names. People are counted and never named.
Shared code	The files that most other files use, such as copybooks, headers, interfaces and shared modules, ranked by the number of files that use them, with the names those files use most. gitta reads them with the same code readers it uses at merge time. Links between repositories show when one repository uses names that another one provides.
History replay	The pairs of work that were open at the same time and both landed. For each pair it counts a Git conflict, a clean merge, a warning from gitta and, with a test command, a clean merge that broke the tests and whether gitta would have stopped it.
Return	Breaks caught, broken builds avoided, conflicts found early and the repair hours they cost, for the period and per year at the same rate.
Rollout plan	The repositories and teams to start with, ordered by overlapping work and how much shared code they have. Teams come from `CODEOWNERS` when the repository has one, and from top folders when it has none.

How the replay works

A piece of work is a merge into the main branch, a squashed pull request with its original head, or a merged pull request from the GitHub API. Two pieces overlap when one started before the other landed. For each pair gitta takes their merge base and merges them with git merge-tree. Then it runs gitta pr-check on the pair, the same check it runs on a pull request.

With --gate, gitta also runs your test command on each side and on the merged code. When the merged code fails, it runs the tests again. A pair counts as a break only when both sides pass alone and the merged code fails twice. For each break, gitta then runs its own test gate on the pair to see if it would have stopped the merge. This is the method of the published replay of 733 agent pull request pairs.

Terminal

$ gitta discover . --gate "make test" --since 3m

Use the command your CI runs. The tests run in temporary worktrees of the copy, one at a time per job.

Your own figures

The return section multiplies the measured counts by repair time. Give your own figures. The report marks every value you did not give as an assumed default.

Option	Meaning
`--hours-per-incident H`	Hours to find and repair one clean merge that broke the build or tests
`--hours-per-conflict H`	Hours one Git conflict costs when it is found at merge time
`--cost-per-hour C`	Your cost of one engineering hour, to show the hours as cost
`--currency X`	The currency label shown next to cost

The per year figures scale the measured rate from the replayed pairs to all overlapping pairs and from the period to a year. They describe your past work and make no promise about future work.

All options

Option	Meaning
`PATH` or `URL`	Repositories to read. Addresses are cloned into the work folder.
`--since 6m`	How far back to replay, in days, weeks, months or years, such as `90d`, `12w`, `6m` or `1y`
`--out DIR`	Where the report and the work folder go. The default is `gitta-discover`.
`--gate CMD`	The test command to run on each side and on the merged code
`--github-token-env VAR`	Read merged pull requests from the GitHub API with the token in this variable. Without it, gitta also reads `GITHUB_TOKEN` when it is set.
`--max-pairs N`	Replay at most N pairs per repository, chosen evenly across the period. The default is 400.
`--jobs N`	Pairs replayed at the same time. The default is 2.
`--license-file F`	Your gitta Enterprise licence. `GITTA_LICENSE_FILE` also works.

Without a licence, the report covers the first two repositories and says it is an evaluation. See Licence.

Long runs

Progress goes to standard error, with the pair in work and the time left. gitta saves each finished pair in --out. When a run stops, run the same command again and it continues where it stopped. A run with a different period, test command or list of repositories starts the replay again and keeps the copies.

Read the pairs in pairs.csv to check any result by hand. Each row has both commit ids and their merge base, so git merge-tree and your tests give the same answer on your own machine.