borg-check(1)

📦
version 2.0.0b25 · 5 versions
, in ubuntu stonking

💖 borg-check(1) 💖

From the borg backup tool, bestie. This is the manual page for checking repository consistency, and it's lowkey one of the most important vibe checks your backups will ever get. 🫶

✨ Name ✨

borg-check — checks repository consistency. That's the whole name, no cap. It's the command that looks at your repo and goes, "okay bestie, are you actually okay?" 💅

🦋 SYNOPSIS 🦋

borg [common options] check [options]

💖 DESCRIPTION 💖

The check command verifies the consistency of a repository and its archives. It's giving two major steps, and both of them matter. Periodt.

  1. Checking the consistency of the repository itself. The objects in the index/ and packs/ namespaces are named by the store hash of their content, so such an object is intact if and only if the hash of its content still equals its name. The check verifies the (small) index objects first and, only if they are intact, all packs. It also cross-checks the chunk index against the packs present in the repository to detect referenced but missing packs. Bit rot and other types of accidental damage can be detected this way, but as content-addressing is not a MAC, this step does not detect tampering of the packs. The index objects are also authenticated with the key when they are loaded for that cross-check. A corrupt index ends the check after this step, as the archives check needs it, unless --repair is given (see below). This step also verifies the repository defaults object (see borg repo-create): it must be present and authenticate with the key. Running the repository check can be split into multiple partial checks using --max-duration. For <ssh://> repositories, the server computes the hashes, so the pack contents do not have to travel over the network. For other remote backends, borg usually has to read (download) the objects to hash them. 🧚
  2. Checking consistency and correctness of the archive metadata and optionally archive data (requires --verify-data). This includes ensuring that the repository manifest exists, the archive metadata chunk is present, and that all chunks referencing files (items) in the archive exist. This requires reading archive and file metadata, but not data. To scan for archives whose entries were lost from the archive directory, pass --find-lost-archives. It has to look at the metadata of every object in the repository (only for the archive metadata objects it finds that way, it also reads the object data), so it is very time-consuming for big repositories. To additionally cryptographically verify the file (content) data integrity, pass --verify-data, which is even more time-consuming. 😭

When checking archives of a remote repository, archive checks run on the client machine because they require decrypting data and therefore the encryption key. No cap.

Both steps can also be run independently. Pass --repository-only to run the repository checks only, or pass --archives-only to run the archive checks only. Choose your fighter. 🎀

borg check always needs the key, --repository-only included: it loads the key (asking for the passphrase, if needed) before it checks anything and aborts if the key can not be loaded. The way that it refuses to move without the key is honestly iconic.

The --max-age option makes the check reuse the results of previous repository checks: packs whose intact result is younger than the given timespan (e.g. --max-age=4w or --max-age=12m) are skipped, spreading the verification cost over repeated checks. The timespan uses the same markers as --older/--newer: d, w, H, M, S are exact spans, while m and y are calendar units counted from now (so 12m equals 1y). Check results are recorded in any case; --max-age only controls their reuse. Packs recorded corrupt are always re-verified. --max-age affects only the repository check and cannot be combined with --archives-only or --repair. So yes, bestie, it's a whole scheduling moment. 🗓️

The --max-duration option splits a long-running repository check into several partial checks. After the given number of seconds, the check is interrupted. A partial check verifies the least-recently-checked packs first, so repeated runs cover the whole repository. Add --max-age to also skip packs whose result is still younger than the given age: once every pack has a recent result, further runs re-check each pack at most once per --max-age, and no faster than the per-run budget allows. Assuming a complete check would take 7 hours, running a daily check with --max-duration=3600 --max-age=1w (1 hour) results in one full repository verification per week. Partial repository checks run neither archive checks nor repair mode, so --max-duration requires --repository-only and cannot be combined with --archives-only or --repair. It's giving "we'll get there when we get there" energy, but scheduled. 💀

Note: A partial repository check verifies the repository files in exactly the same way as a full repository check does — the difference is only how many of them one run gets to. What a partial run does not do are the archive checks: because --max-duration requires --repository-only, neither the archive metadata checks nor the cryptographic data verification of --verify-data run. Partial checks are therefore mostly useful for very large repositories where a full check would take too long. Lowkey a lifesaver for giant repos. 🐘

The --verify-data option will perform a full integrity verification of data, which means reading the data from the repository, decrypting and decompressing it. It is a complete cryptographic verification and hence very time-consuming, but will detect any accidental and malicious corruption. Tamper-resistance is only guaranteed for encrypted repositories against attackers without access to the keys. You cannot use --verify-data with --repository-only. Not me trying to skip the hard part — you literally can't. 🙈

--verify-data also always verifies that each chunk's content matches its chunk id, which normal reads do not do by default (see BORG_ASSERT_ID). Running it periodically is therefore recommended. Set a reminder, bestie. ⏰

The --find-lost-archives option will also scan the whole repository, but tells Borg to search for lost archive metadata. If Borg encounters any archive metadata that does not match an archive directory entry (including soft-deleted archives), it means that an entry was lost. Unless borg compact is called, these archives can be fully restored with --repair. Please note that --find-lost-archives must look at every object in the repository and is thus very time-consuming. You cannot use --find-lost-archives with --repository-only. It's the "dig through every drawer in the house" of options. 🕵️‍♀️

You can influence how the archive part of the Analyzing archive ... output is formatted by giving a custom format using --format (see the borg repo-list description for more details about the format string). Customize your little report card, fr fr. 💅

If the borg check process receives a SIGINT signal (Ctrl+C), it stops at the next safe boundary, leaving the repository and its chunk index in a consistent state. The repository check stops after the current pack; --verify-data and --find-lost-archives stop after the current chunk; the archive check stops after the current archive item, with --repair between whole archives. Results recorded before the interrupt are kept, so a later check does not re-verify those packs until they are due again. With --repair, an interrupted archive check may leave some archives already repaired and others not yet processed, so run borg check --repair again to finish. It doesn't ghost you mid-task; it just pauses politely. ✋

borg check rebuilds the chunk index from the packs when --repair is given or when the stored index cannot be used. Ctrl+C stops that rebuild after the current object and discards the partial index: it lacks chunks that are still in the repository, so the check would report them as lost. After a --repair that stored or deleted chunks, borg re-reads the packs the repair wrote, makes the chunk index match them and stores it; that always runs to completion, also after a Ctrl+C. So that part is the main character and it finishes its scene. 👑

🛠️ About repair mode 🛠️

The check command is a read-only task by default. If any corruption is found, Borg will report the issue and proceed with checking. To actually repair the issues found, pass --repair. That's the switch that changes everything. 🚨

Note: --repair is a POTENTIALLY DANGEROUS FEATURE and might lead to data loss! This does not just include data that was previously lost anyway, but might include more data for kinds of corruption it is not capable of dealing with. BE VERY CAREFUL! 😭

Pursuant to the previous warning it is also highly recommended to test the reliability of the hardware running Borg with stress testing software. This especially includes storage and memory testers. Unreliable hardware might lead to additional data loss. Basically, do not run this on a laptop that has been dropped down the stairs. 💀

It is highly recommended to create a backup of your repository before running in repair mode (i.e. running it with --repair). Yes, a backup of your backup, bestie. The irony is real, but so is the data loss risk. 🫶

Repair mode will attempt to fix any corruptions found. Fixing corruptions does not mean recovering lost data: Borg cannot magically restore data lost due to e.g. a hardware failure. Repairing a repository means sacrificing some data for the sake of the repository as a whole and the remaining data. Hence it is, by definition, a potentially lossy task. It's giving "we saved what we could," not "we saved everything." 🥲

In practice, repair mode hooks into both the repository and archive checks:

  1. When checking the repository's consistency, repair mode rebuilds the repository index from the packs if the index is corrupt, provided every pack matches its store hash. If any pack fails its store hash, the repository check leaves the index and the packs untouched and reports it; salvaging the intact objects of such a pack is not implemented yet (refs #8572). The rebuild authenticates each object's header and metadata with the key, leaves an object that fails this out of the index and reports it as an error. Repair mode also removes the index entries of the chunks stored in missing packs (packs the index references, but that are absent from the repository). Only a full borg check --repair repairs the archives that reference these chunks, --repository-only does not. A missing or corrupt repository defaults object is replaced by empty defaults, so the repository can be used again; the commands then use the built-in defaults. So it patches the index, drops the broken bits, and keeps it moving. 🧹
  2. When checking the consistency and correctness of archives, repair mode might remove whole archives from the manifest if their archive metadata chunk is corrupt or lost. Borg will also report files that reference missing chunks. It's not being dramatic; it's being honest. 💔

If --repair --find-lost-archives is given, previously lost entries will be recreated in the archive directory. This is only possible before borg compact would remove the archives' data completely. So if you want those lost entries back, you gotta move before compact does its thing. ⏳

✨ OPTIONS ✨

okay bestie, before we get into the good stuff — peep borg-common(1) for all the common options that basically every Borg command shares. this page is just the extra sauce 💅

🎀 options 🎀

  • --repository-only — check ONLY the repository, nothing else. that's it, that's the whole vibe.
  • --archives-only — flip it around: check ONLY the archives. no repo drama today 🙈
  • --verify-data — do the full cryptographic archive data integrity verification. like, the real deal, actual maths, actual crypto. ⚠️ heads up tho: this conflicts with --repository-only — you can't do both, pick a lane bestie.
  • --repair — when the check finds messiness, this tries to repair any inconsistencies found. messy fixer-upper era.
  • --find-lost-archives — attempt to find lost archives. like a "have you seen my archives" missing-poster situation 👀
  • --max-age TIMESPAN — reuse intact-pack check results that are younger than TIMESPAN, e.g. 4w or 12m. no need to redo work that's still fresh, we're efficient.
  • --max-duration SECONDS — only do a partial repository check, capped at SECONDS seconds. default is unlimited, so if you don't set it, it just goes until it's done.
  • --format FORMAT — set the output format for the archive part. default is "{archive} {time} {id}".

🌈 Archive filters 🌈

these are the "which archives are we even talking about" controls. pick your fighters 💖

  • -a PATTERN, --match-archives PATTERN — only consider archives matching all patterns. for the full scoop, run 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, applied after all the other filters are already applied.
  • --last N — consider the last N archives, also after the other filters.
  • --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 👀

🌸 Author 🌸

The Borg Collective

that's the whole page babes, you made it 🫶 go forth and borg-check responsibly. this icon was written by The Borg Collective, it's from the 2026-10-07 era, and it lives as borg-check(1) 💜 no cap, you've got this ⭐

📦 where this page comes from