borg-analyze(1)

✨ NAME ✨

okay so bestie, this is borg-analyze from the borg backup tool — she analyzes archives 💅

---

🌸 SYNOPSIS 🌸

borg [common options] analyze [options]

---

🦋 DESCRIPTION 🦋

So borg analyze looks at the archives that match the normal archive selection options (like -a series_name), OR she takes your whole repository and decomposes it into groups of archives — that second one is the --group-by thing, we'll get there 🫶

💖 Deduplicated size of a set of archives 💖

For whatever (matching) set of archives you're considering, borg analyze reports the source size (that's the uncompressed source data) and the stored size (compressed, exactly how it sits in the repository), plus the compression factor that relates the two (stored / source):

• the deduplicated size of the set: the summed size of the union of chunks the considered archives reference — chunks shared within the set get counted once, periodt;
• the exclusive size of the set: the summed size of chunks referenced only by the considered set and by no other archive — i.e. the space that deleting the whole set would free (assuming the other archives stay). it's giving "what do I actually get back" energy 🔥

On top of that, the unreferenced chunks get reported too: chunks in the repository that no non-deleted archive references — so like, what borg compact could free in the current state of the repository. Only their stored size is known, because a chunk's source size is only recorded in the archives that reference it (no archive → no source size, that's just how it is 😭). And heads up: chunks belonging to soft-deleted archives count as unreferenced here, even though borg compact keeps them when the repository is damaged (so that borg undelete stays possible).

not me about to forget this one: if no archive filter is given, all archives are considered — every referenced chunk is then trivially exclusive to them, so only the repository-wide deduplicated size is shown. slay, but also, that's the whole repo lol.

The stored sizes come from the repository's chunk index; the chunk membership and the source sizes come from the per-archive references cache that borg compact maintains — which means unchanged archives usually do not need to be opened 👑 fast fr fr.

🌈 Decomposition by group of archives (--group-by) 🌈

With --group-by, the whole repository gets decomposed into groups of archives instead. The groups are formed by the given comma-separated archive attributes name, host, user and tags — the exact same grouping that borg prune --group-by uses, so the numbers below relate to the same units that prune applies its retention rules to 🎀

Archives sharing a name form a series, so --group-by name usually groups all backups of one source. In a repository shared by multiple machines or users that is not specific enough, because they may use the same series name for their own, unrelated data — use --group-by name,host there, bestie, trust 💅

Every chunk is counted in exactly one row, so the rows add up to the repository's deduplicated size:

1. one row per group, showing what is exclusive to it: no archive of another group references these chunks, so deleting all archives of that group would free them;
2. one row for the chunks shared by two or more groups;
3. one row for the unreferenced chunks (see above).

This answers "which group costs how much, and what would I get back by dropping it" for all groups at once, in a single pass over the archives. iconic. But because the shared and unreferenced rows can only be determined by looking at every archive, --group-by always covers the whole repository and cannot be combined with archive filters. no cap.

Grouping by more attributes moves chunks from the group rows into the shared row: if two hosts back up identical content, --group-by name reports it as exclusive to that name, while --group-by name,host correctly shows that deleting either host's archives alone would not free it. the accuracy is giving main character energy ✨

💀 Hot spots 💀

If at least two archives match, borg analyze additionally iterates over all matching archives, over all contained files, and collects information about chunks stored in all directories it encounters. It considers chunk IDs and their plaintext sizes and adds up the sizes of added and removed chunks per direct parent directory, and outputs a list of directory: size 🍓

You can use that list to find directories with a lot of "activity" — maybe some of these are temporary or cache directories you forgot to exclude 🙈 (we've all been there). To avoid including these unwanted directories in your backups, you can carefully exclude them in borg create (for future backups) or use borg recreate to recreate existing archives without them.

🧚 JSON output 🧚

With --json, the same numbers are emitted as a single JSON object instead of the text report, with raw byte values rather than formatted sizes. The default mode fills the dedup_size and hotspots keys, --group-by fills the by_group key. The compression factor is not included: it is stored_size / source_size. See json_output for the object's structure.

---

👑 OPTIONS 👑

See borg-common(1) for common options of Borg commands.

🌸 options 🌸

• --group-by KEYS — decompose the whole repository by groups of archives, grouped by the given comma-separated archive attributes (not combinable with archive filters); valid keys are: name, host, user, tags
• --json — format output as JSON

🎀 Archive filters 🎀

• -a PATTERN, --match-archives PATTERN — only consider archives matching all patterns. See borg help match-archives.
• --sort-by KEYS — Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
• --first N — consider the first N archives after other filters are applied
• --last N — consider the last N archives after other filters are applied
• --oldest TIMESPAN — consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
• --newest TIMESPAN — consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m.
• --older TIMESPAN — consider archives older than (now - TIMESPAN), e.g., 7d or 12m.
• --newer TIMESPAN — consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.

---

💜 SEE ALSO 💜

borg-common(1)

---

🫶 Author 🫶

The Borg Collective

---

okay that's the whole thing bestie, you're so back 🦋💖 this was borg-analyze(1) from 2026-10-07 — go analyze something and slay, ily, byeee ✨