Git storage compaction (free up disk space)
Git quietly piles up junk until commands slow and the store eats tens of gigabytes. The Git storage card shows each repository's real size and compacts the ones you pick.
On this page
What it is
Where: Settings → Diagnostics → Git storage
Git quietly accumulates junk. Every fetch, every branch, every worktree leaves loose objects and extra pack files behind, and nothing removes them on its own. On a busy repo this grows until git itself gets slow — every command has to scan the pile — and it can eat tens of gigabytes.
The Git storage card lists every git repository Omniscio knows about with its real size on disk, then compacts the ones you pick. On a badly-bloated store this routinely reclaims several gigabytes and makes every git operation noticeably faster.
Where to find it
How to use it
- Open Settings → Diagnostics and find Git storage.
- Tick the repositories you want to compact. Each row shows its size on disk, pack-file count, and loose-object count, so you can see which ones are actually bloated.
- You often need not do anything here at all: a store that has grown bloated is compacted at the
next start on its own (see What it does by itself below). If you want to force it anyway,
choose one of:
- Compact on next restart — nothing happens now; it runs the next time you start Omniscio.
- Restart & compact now — Omniscio closes and does it immediately.
- On the next launch the startup screen shows live progress. When it finishes, the card reports what it reclaimed.
A scheduled compaction shows a Scheduled for the next restart line with a Cancel button, so a pending request is never invisible.
How it behaves
Why it needs a restart
A full-strength compaction rewrites the repository's object store. It cannot safely run while anything else is using that repository — and Omniscio itself is constantly running git in the background for its sessions, worktrees, and branch tracking.
So instead of trying to hunt down and kill those processes, Omniscio does the compaction during its own startup, before it opens its window and before any session resumes. At that exact moment it has no git activity of its own, which is the quiet window the compaction needs. Nothing gets killed, and nothing races.
What to expect
- How long depends on the repository. A small one is done in seconds; a large, long-neglected one can take 5 to 30 minutes. The startup screen names the repository and which of the three steps is running out of how many, and because a single step can run quietly for many minutes it keeps a quieter line underneath saying it is still working — so a long wait never looks stalled.
- There is no time limit. A tidy-up runs until it is done, however long that takes. When you started it, the startup screen stays up the whole time and tells you a large project can take a long time; Skip is always there and stopping is safe. A tidy-up Omniscio starts by itself runs in the background after the window opens, so it never makes you wait.
- A long compaction is never reported as a failed start. Omniscio's "opened to a blank screen" check does not count the time it spends compacting, so a slow run sends no crash report and puts no "blank screen" card in your inbox. If the dashboard really does stay blank afterwards, that is still reported.
- And neither is a slow start after an upgrade. Before it applies an update to your database, Omniscio copies the whole database first so the upgrade has a way back. On a large database that copy takes minutes and is limited by your disk, not by the app — the startup screen counts its progress, and the blank-screen check sets the time aside, so a long copy no longer raises a false "blank screen" alert. If the dashboard still does not appear once the copy is done, that is reported exactly as before.
- While Omniscio starts, it keeps itself awake (Mac). If you start it and switch to something else, macOS would otherwise suspend it until you came back — the app would sit half-open and finish its startup minutes later. From the moment its startup check begins until the dashboard is up, Omniscio now asks the system not to suspend it, so a launch finishes whether or not you are watching. It is macOS-only, and the request is dropped the instant the interface is ready.
- A blank screen is never reported for an app that was not running. The 120-second check measures its own clock, and it now records how late that clock actually ran. A frozen or suspended process is named as exactly that in one line, instead of reading as an interface that never loaded.
- You can stop it at any time. The startup screen shows a Skip and open now button for as long as the compaction runs, with a line under it explaining what the tidy-up is and that stopping costs nothing. Pressing it stops the work immediately and opens Omniscio — whatever had already finished is kept. The button comes down with the run, so it never shows up on a normal startup and never lingers once the compaction has ended.
- Your sessions are safe. They are suspended when Omniscio closes and resume automatically afterwards.
- Force-quitting during it is also safe, though Skip is the better exit. Git writes the new data to a temporary file and only swaps it in at the very end, so an interrupted compaction changes nothing.
- It never deletes your work. It reorganizes how git stores what it has, and a compaction you schedule also removes data nothing uses any more (next section) — never anything a branch, recent history or open worktree still uses.
- If it stops early, the card says why — whether you skipped it or it ran out of time — and any repository it never reached is listed rather than quietly dropped.
A compaction you schedule also removes data nothing uses
Git keeps everything it ever stored, including the leftovers of branches and work nothing points at any more. A compaction you schedule from the card also clears those out:
- What it keeps: everything any branch, recent history entry or open worktree still uses — including local copies of files the remote (GitHub) also holds — and anything that was in use during the last two weeks.
- Two weeks unused, then gone. A run deletes data nothing has used for two weeks, and sets aside newer unused data with its own date; a later compaction you schedule deletes it once it has gone unused for two weeks. Git dates unused data by the file it is packed in, and a busy repository's files are re-dated every day, so there the first run mostly sets data aside and frees little. The card's result line says how much a run set aside.
- Nothing is removed until the new copies are fully written, so Skip, a crash or an error removes nothing — the card then says why this part was skipped.
- Only when you schedule it. A request that arrives without your mark — a headless write of the list alone, or a legacy entry — never deletes anything.
- It needs about twice the repository's size free, plus a gigabyte, while it works; with less, only this part is skipped and the rest of the compaction still runs.
When it refuses (and says so)
Each of these is reported in plain English, and nothing is changed:
- The folder has been moved or deleted.
- The folder is not a git repository.
- The folder is a linked worktree rather than a main repository — compacting it would act on the parent repository instead, which is not what you asked for.
- The drive does not have enough free space. A compaction writes the new consolidated data before deleting the old, so it temporarily needs roughly one and a half times the repository's current size, plus a gigabyte of margin.
On a git older than 2.53
Git 2.43 through 2.52 cannot combine the pack files of a partial clone (a repository that keeps some of its files only on the server, as Omniscio's own checkout does). On such a git the compaction skips that one step instead of failing: it still tidies references, removes unused data when you scheduled it, and cleans up old worktree records, and the Git storage card says "Pack files were not combined … Update git to 2.53 or newer." Update git, then schedule the compaction again. A full clone is unaffected on any git, and so is any git 2.53 or newer. The background maintenance skips the same step on such a git, and the app-closed recovery script stops before it changes anything.
Does this replace the automatic maintenance?
No — it complements it. While Omniscio is running, a repository above the pack-count threshold stays eligible for a consolidation attempt, day or night, regardless of whether the machine was busy when the attempt began. The clock runs from the last attempt that actually folded packs, not from the last attempt of any kind, so a run that was killed or folded nothing does not buy the store a quiet window while new packs keep arriving. The batch keeps running even when load telemetry is stale; Git commands retain their timeout. A five-minute sweep serves one repository at a time and rotates its starting point, so an attempt can happen later than its interval when many repositories need work. A completed command that folds no packs is reported as a no-op and retried after a cooldown, not counted as successful upkeep. An attempt keeps folding, in bounded batches, until the pack count is back at or below the threshold it triggers on — so one attempt finishes the fold instead of stopping after a single batch and leaving the rest for the next window. This card still provides full-store compaction on restart when you choose it or when startup detects a bloated store.
The 15-minute interval is an eligibility clock, not a timeout. The consolidation run starts with
a 45-minute default budget (AMC_GIT_PACK_CONSOLIDATE_TIMEOUT_MS can change it). The fold, index
verification, and expiration commands share one deadline; each child gets only the time left.
Waiting for a stopped child and cleaning up can extend the overall pass beyond that deadline.
The background lane deletes old unused data too. It is not repacking only. On a quiet machine the
everyday maintenance also runs a deep prune — git repack --cruft -d, with git's own grace — that
permanently drops objects which have been unreachable for 14 days or more: an abandoned commit, a
rewritten history, a dropped stash, work from a branch that was thrown away. It runs at most once per
repository every 24 hours, and only when nothing is using the store, so it never competes with
live work. This is the one part of the automatic lane that deletes without you scheduling anything;
the compaction you schedule does the same job on demand. Both leave alone anything a branch, a
history, or a worktree still uses.
You can stop the whole background lane while the app is running — no restart. The switch is the
governor git-store-maintenance: turning it off from a terminal stops every tier at the next tick, and a repack or drain that is already running
stops at its next batch or its next clean-up step (what it already finished stays). Turning it
back on resumes it, and a listing shows where it stands. If that switch file ever cannot be read, the
background lane stands down rather than guess, and the log says so once per sweep. It is a person's
switch, not an agent's, and it refuses anything but an interactive terminal.
The "Git's commit graph is behind" notice
The commit graph is a small index git keeps next to its packs so that history, ancestry and "which commits are on this branch" questions can be answered without opening every commit. Omniscio refreshes it on its own as part of the background maintenance. When that refresh stops getting done, you can get an inbox card titled Git's commit graph is behind (git-store-commit-graph-behind). It says how long ago the graph was last refreshed and what the refresh window is, and it adds how many commits are currently uncovered.
Nothing is lost. Git falls back to reading those commits from the pack files, which is slower but gives the same answers. The card is a heads-up that the refresh itself is not completing, and it clears itself the moment a refresh catches up. There is no button because there is nothing for you to press.
How it decides to speak up:
- It goes by age, not by a commit count. A busy repository can add dozens of commits an hour, so a count would fire on a perfectly healthy store. The card fires when the graph's age passes three times the refresh window (the window is 6 hours, so 18 hours). The uncovered count on the card is detail only.
- It must see it twice. The check runs from the same 5-minute background sweep as the rest of the storage upkeep, and the card is raised only after two readings in a row are past that line. A single stale reading raises nothing.
- It clears itself. A reading back inside the line withdraws the card.
- A store with no graph at all counts as never refreshed. That is a real state and it is treated as behind.
- A store it cannot read says nothing either way. An unreadable store neither raises the card nor clears one that is already showing.
- Who sees it. The card is raised only on a developer build, or for a repository you have turned the Dev Pipeline on for.
The refresh is scheduled every 6 hours per repository and stands down while the machine is busy, so on a busy machine it can go longer than 6 hours between refreshes — expected, and why the notice is not raised the moment the graph is a little old. It is still guaranteed a turn on a machine that never goes quiet: past its own floor (default 2 hours) it runs anyway, at low priority. That guarantee does not cover losing the slot to a heavier job — the everyday clean-up and the deep prune take priority, and on a heavily-used repository the refresh can wait behind them. The notice is how that shows up.
Why a long compaction no longer starves the graph. The standalone graph writer takes the same store lock as a drain or repack, so it is turned away for the 5 to 18 minutes one of those holds the lock. To close that gap, the maintenance run writes the graph itself, before it lets go of the lock, whenever a tier actually ran and the machine is calm. That write keys on a 15-minute cadence, not the 6-hour one.
Turning it off. AMC_DISABLE_GIT_AUTO_MAINTENANCE switches off the whole background maintenance and silences this check. AMC_DISABLE_GIT_PERF_MAINTENANCE is different: it switches off the graph writer (the standalone one and the one inside a maintenance run), so it does not silence the card. With the writer off, the graph ages and the card can appear.
What it does by itself
When a store has grown genuinely bloated, Omniscio compacts it during the next start, with nothing asked of you — the fallback that keeps storage from running away on a machine whose everyday clean-up keeps standing down because it is busy. A store that is already tidy is skipped before any work begins, so a start whose stores are fine pays nothing for this and starts no git process at all.
Two things make a store "bloated", not one. It is tidied when its pack-file count has reached the same line the everyday background clean-up uses, or its loose objects have reached the count at which that clean-up stops waiting for a quiet machine. A store with a perfectly ordinary pack count can still be one whose loose pile has got out of hand, and that is exactly the case the pack count alone could never see.
The pile is drained in slices, and it now aims at a floor. The everyday clean-up packs loose objects in bounded pieces — a piece at a time during the working day, and as much as one run can safely carry during the night window — and it keeps going until the pile is down to a low mark rather than stopping the moment it dips under the line that started it. That distinction is what lets it catch up after a busy day instead of forever chasing its own trigger: a store with more than half a million loose objects is 143 pieces of work at the shipped piece size, and the old fixed ceiling of 64 pieces per run could never clear it. Each piece also yields to the load gate between pieces, so the work yields the moment your machine needs it. What each piece cost is recorded — the box's page faults per second either side of it — and a readout prints it per repository, along with whether the run reached the floor. The store is locked for the whole tick and that lock is taken once, so a tick that loses it to another process does not wait: it is skipped, and the readout counts those skips and the time the other holder had held the lock, which is the only place contention is visible at all.
Duplicate copies a burst of fetches leaves behind are cleared on their own. On a repository cloned without its file contents (a partial clone), every fetch can copy things you already had into a new pack, and several fetches at once can each copy the same set. On 2026-11-13 that grew one store from about 25 GB to 60 GB in an hour. Now, once 100 MiB of such copies pile up, the background index refresh runs and then removes every copy whose contents another protected copy already holds. A copy is removed only when every object in it is held by another pack carrying the same "can be refetched" marker, so that marker is never lost. A copy git is still reading is left and tried again an hour later. Each pass logs how many packs it removed and how much space it freed.
Fewer loose objects are written in the first place. Draining the pile treats the symptom, so
Omniscio now writes far less of it. A merge it runs only to compare two branches now leaves nothing
behind in your repository: it works in a temporary store that is deleted afterwards. A write that
must be kept, such as a rescued worktree or a rehomed cloud branch, is saved as one compact file
instead of dozens of loose ones. The Git packed object writes setting (gitPackedObjectWrites,
on by default) controls the second part; switched off, those writes go back to the old way.
This was proven on a real store, not a fixture: a fresh --filter=blob:none clone walked to the
floor in one night run while the old ceiling stopped at 64 pieces with about 300 objects left, no
reachable object lost. The clone is what the stores that bloat actually are, and the loose objects
the proof writes into it exist nowhere else — no origin copy — so a piece that lost one could not
be quietly fetched back into looking fine.
The check is plain file reads — never a git process — and it refuses without asking for three things:
a repository whose .git belongs to a linked worktree (compacting it would act on the parent repo),
a store the loss-protection watch believes is missing, and anything that is not a repository. A store
whose size could not be read counts as tidy rather than being acted on, so a failed measurement can
never be the reason your storage is rewritten. A run started this way has no time limit, runs the
smallest repositories first so a huge one never holds the others back, never deletes unused data (unlike the everyday background lane, which
deep-prunes objects unreachable for 14+ days — see above), and can be turned off outright with
AMC_DISABLE_GIT_BOOT_AUTO_COMPACT.
And it tells you what it did. When a start really tidies a store, you get one line in your inbox naming the repository with the pack count and size before and after and how long it took, and it takes you straight to the Git storage card. A start that tidies nothing — the ordinary case, where every store is inside its limits, or where the fold found nothing to do — says nothing at all; "it ran successfully" is not the same as "your storage changed", and only the second is worth a line. A run that could not finish says so instead of claiming success, and names the repository it could not finish on. This is the whole point of the automatic side: you do not have to remember to check anything.
A run that had to stop says so too, and is tried again. A run only stops early if Omniscio quits while it is still working. You then get a line saying which repository it stopped on, and it is tried again the next time Omniscio starts. Stopping early is never read as "this store cannot be tidied" — nothing is stood down for good on the strength of a run that was cut short.
(This is the tidying Omniscio runs by itself in the background. A tidy-up you scheduled from the Git storage card is a different run: it happens before the window opens with the startup screen in front of you, and if you Skip it, the card you already have tells you what happened.)
No store is ever too big. Until November 2026 a start skipped a store it predicted could not be tidied within its time limit, and showed "Project storage is too large to tidy up at startup". That skipped exactly the store that most needed tidying, so every time limit was removed: every store over its limits is tidied, for as long as it takes. If you still have that old card, the next start withdraws it.
An earlier version of this was removed, and the difference matters. In September 2026 Omniscio escalated on its own whenever a store looked untidy, and it was taken out because it could not change what the background clean-up actually did — it watched loose objects while the fold acts on packs, so it promised more than it delivered. What replaced it measures the one thing the fold acts on, through the same threshold the background clean-up reads, which is what lets it act in exactly the case that clean-up is blocked.
A request the card did not make — a legacy entry, or one written headlessly without the user flag — never holds your startup screen: it is cleared and runs in the background after the window opens, with no time limit, like Omniscio's own tidy-up.
Git ref cleanup at launch (Omniscio's own repository)
Every git command slows down as the number of branches and other refs grows, and agents create thousands a day. So when you start Omniscio from its development checkout, it tidies them up first:
- Before the window opens, right after the storage compaction above, it removes refs whose work is already on master. Each one is saved in a restorable archive first, so nothing is lost.
- Progress shows in the terminal: the ref count before and after, and what was removed.
- The first launch catches up on the backlog, checking every branch once, one line per pass. It stops after an hour at most and carries on at the next launch; stopping it early loses nothing.
- Later launches run one shorter pass. On a busy computer that can take several minutes.
- It never runs while Omniscio is open, and never from a test copy of the app. While the app is open, a light pass every 10 minutes removes only refs already proven safe.
- Unfinished work is never touched. Branches whose work is not on master yet are listed in
~/.amc/unfinished-branches.csv, and each hub gets one card in your inbox with the newest of them, refreshed at every launch.
Turning it off: Settings → Diagnostics → Clean up Git refs at launch. Off brings back the older every-10-minutes cleanup and removes the hub cards.
Related
What Omniscio's own maintenance jobs do, and when they run, is covered by Dev Pipeline Maintenance.
When a killed writer leaves damage behind
A git command that dies mid-write can leave the pack folder in a state git cannot read: a
pack-*.pack whose .idx never landed, a multi-pack-index that fails its own verify, or a lock
whose writer is gone. Omniscio repairs that residue at the next start, before any tidy-up tries to
use the store.
What it does, per store:
- A pack with no index is indexed (
git index-pack), the new index is verified (git verify-pack), and only then moved into place. A pack that cannot be indexed is moved into.amc-quarantine/packs/inside the store — never deleted, so nothing is lost and a person can still inspect it. - A multi-pack-index that fails its own verify is moved aside and git rebuilds it. Nothing is
moved while its
.lockis present, because that means a writer, not damage. - A stale lock left by a dead run is moved aside by the same owner that the scheduled tidy-up uses.
Everything the pass does is recorded, and GET /boot-receipts returns those records as
gitStoreRepairs. An empty list is the healthy answer.
It also records the git version this computer runs and whether the repository is a partial clone. That matters because the pack fold cannot run below git 2.53 on a partial clone — the tidy-up skips that step and says so, and when both conditions hold the app raises one card naming the version and the Toolchain page that updates git. If you see that card, updating git is the whole fix; nothing else needs changing.
Last verified 2026-10-24