How does “Size mismatch tolerance” option really work?

[tr4cks]

I'm using hardlink mode and I want to make sure the files are actually the same, and manually check if any new files are present. If I set the “Size mismatch tolerance” option to 0%, will it still match torrents that aren't the same size but stop during the recheck, or are the two linked?
In short, I’d like a partial mode but want it to be very strict when new files are added.
Thank you

[yhay81]

They are linked. In the current implementation, Size mismatch tolerance is used for two related gates:

1. During matching/materialization, the required byte coverage is 100% - tolerance.
2. After a required recheck, the auto-resume threshold is also derived from it (with a 90% floor for large tolerances).

So an explicit 0% is strict: the coverage threshold is 100%, and the recheck resume threshold is 100%. It is not a “allow partial, then stop after recheck” switch. A partial hardlink match with any non-ignored missing bytes will normally be rejected as below_threshold before the torrent is added. If a torrent is added for some other reason that requires rechecking, it will only auto-resume at 100%.

For the workflow you described, I would use:

• a small non-zero tolerance large enough to admit the expected sidecar/new files;
• leave Skip recheck disabled;
• enable Skip auto-resume for the relevant source (RSS/Completion/Webhook/etc.).

That lets qui create links for the files it has, add the torrent paused, run the recheck, and leave it paused for your manual inspection instead of resuming it automatically.

There is also a separate safety gate: in hardlink mode, unmatched extra files must be piece-boundary safe; otherwise qui skips the cross-seed to avoid qBittorrent modifying hardlinked source data. Reflink mode is the safer option when you need partial downloads across shared piece boundaries.

The current docs explicitly say the setting “also determines auto-resume threshold,” and the tests confirm 0 -> 100%, 5 -> 95%:

• Rules: Size mismatch tolerance
• Hardlink mode: pause/extra-file behavior
• Threshold tests

[tr4cks]

First of all, thank you for taking the time to give me such a thorough answer. It's true that this part isn't easy to understand with all these different scenarios.

For the workflow you described, I would use:
[...]

The problem with this approach is that, when it comes to torrents that contain exactly the same files, they won't start seeding right away.

---

To provide some context, I'm currently using cross-seed[.]org, a tool that lets me perform a partial match while ensuring that if new files are present, I can check them first (with a few specific settings). As I use qui and love this software, I thought I'd integrate cross-seed directly into it. I'm aware of reflinks, but I don't plan on changing my filesystem.
I don't know if there are plans to separate these two parts or not. Maybe I should open an issue?

There is also a separate safety gate: in hardlink mode, unmatched extra files must be piece-boundary safe; otherwise qui skips the cross-seed [...]

So, despite all the other rules, if the file isn't piece-boundary safe, the cross-seed will never happen?
This is problematic because, in BitTorrent hash v1, this scenario happens almost every time.
With hardlinks, wouldn't it be better to let qBittorrent perform a recheck, and if the recheck is invalid, let the user check it? And in all other cases, set the torrent to seed directly.

[yhay81]

You are correct: my suggested Skip auto-resume configuration does not preserve immediate seeding for perfect matches. I should have made that trade-off explicit.

The current controls cannot express exactly this policy:

• complete link tree / no extras → start seeding immediately;
• partial match or unmatched extras → add paused, recheck, and keep paused for manual review.

With Skip auto-resume off, the first case starts immediately, but a safe extra-file case can also resume after its recheck reaches the threshold. With it on, both cases stay paused. So yes, an issue/feature request is appropriate. I would request a separate option such as “keep paused only when a recheck is required” (or “skip auto-resume for partial/extra-file matches”), rather than changing the meaning of size tolerance. The existing Pause Behavior documentation confirms that perfect trees skip checking while extras take the paused/recheck path.

On the piece-boundary question: yes, current hardlink mode skips an unsafe extra-file match, and a recheck cannot make that safe. A recheck is read-only, but if qBittorrent later downloads a missing v1 piece that spans the end of an existing file and the beginning of the extra file, writing that piece can modify the existing file through its hardlink. By the time the user sees a bad result, the shared source inode may already have been changed. That is why the guard is stricter than merely adding paused; the docs state this explicitly under Hardlink Mode → Notes.

So I would split the request in two:

1. Reasonable feature: conditional pause/auto-resume behavior for safe matches, preserving immediate seeding for exact matches.
2. Not safe to disable for hardlinks: the shared-piece guard. Supporting those v1 layouts requires independent writable data (reflink/copy), not merely a later recheck.

That distinction should give the maintainers a concrete, implementable issue.

[tr4cks]

Your suggestions sound great to me. Thanks for your help.
Yes, I understand that it can be a problem when an extra file is part of the same file as the original. It doesn't happen often, so in those cases I recheck the original torrent to make sure everything is okay.