docs(comparison): re-verify the two behavioural subsections against 3.5.0 - #7660
Merged
Merged
Conversation
….5.0
`docs/UPSTREAM_COMPARISON.md` is titled "vs upstream rsync 3.5.0" but declared
itself **Last verified: 2026-07-22 (against 3.4.4)**, warning that every section
"touching path resolution, symlink handling, chroot or daemon access control"
still described 3.4.4 with 3.4.4 line offsets.
That warning was broader than the document's contents. Grepping those four
topics returns 13 lines, and only two subsections make behavioural claims:
§19 Module Chroot Handling and §22 Path Resolution. The rest are wire constants
(`CF_SYMLINK_TIMES`, `CF_SYMLINK_ICONV`, the `DeleteStats` symlink counter) that
the note's own protocol-level argument already covers.
Both subsections re-read against `target/interop/upstream-src/rsync-3.5.0/`.
Every citation in them had drifted:
| claimed | actually at 3.5.0 |
|---|---|
| `clientserver.c:831` = `rsync_module()` | `:739`; the decision block is `:883-895` |
| `clientserver.c:845-862` = the `/./` split | that range is gid handling; the split is `:897-908` |
| `backup.c:187-221` = `link_or_rename` | `:226`; called at `:316` and `:325` |
| `backup.c:288-300` = cross-device recreate | that range is the safe-symlink guard |
| `delete.c:165-174` = backup-before-delete | `:228-230` |
Two claims were also wrong on substance, not just position:
- The chroot table said the unset-and-no-`/./` probe falls back "on `EPERM`".
Upstream tests only `chroot("/") < 0` and switches to false on **any**
failure, logging `strerror(errno)` for the operator rather than branching on
it.
- The backup-before-delete guard was quoted with two terms. Upstream has three:
`make_backups > 0 && !(flags & DEL_FOR_BACKUP) && (backup_dir || !is_backup_file(fbuf))`.
The omitted `DEL_FOR_BACKUP` term is what stops a deletion issued by the
backup machinery itself from recursing into another backup.
The retarget note is narrowed to what it actually covers, and gains an explicit
statement that this document has no section on 3.5.0's confinement model at all
- the resolver, `--confine-root`, `--insecure-links` and the new daemon
directives are owned by `docs/design/upstream-3.5.0-path-confinement-model.md`,
so absence from the compatibility table is not evidence of parity. That was the
reading most likely to mislead once the old blanket caveat came off.
`cargo xtask citations` passes: 9029 citations across 5072 files, every one
naming a file rsync 3.5.0 has at a line that file has. As that gate prints
itself, it does not check whether a cited line *says* what the comment claims -
which is exactly the class fixed here, and why the two subsections were read
against the C rather than re-pointed arithmetically.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs/UPSTREAM_COMPARISON.mdis titled "vs upstream rsync 3.5.0" but declareditself Last verified: 2026-07-22 (against 3.4.4), warning that every section
"touching path resolution, symlink handling, chroot or daemon access control"
still described 3.4.4 with 3.4.4 line offsets.
That warning was broader than the document's contents. Grepping those four
topics returns 13 lines, and only two subsections make behavioural claims:
§19 Module Chroot Handling and §22 Path Resolution. The rest are wire constants
(
CF_SYMLINK_TIMES,CF_SYMLINK_ICONV, theDeleteStatssymlink counter) thatthe note's own protocol-level argument already covers.
Both subsections re-read against
target/interop/upstream-src/rsync-3.5.0/.Every citation in them had drifted:
clientserver.c:831=rsync_module():739; the decision block is:883-895clientserver.c:845-862= the/./split:897-908backup.c:187-221=link_or_rename:226; called at:316and:325backup.c:288-300= cross-device recreatedelete.c:165-174= backup-before-delete:228-230Two claims were also wrong on substance, not just position:
/./probe falls back "onEPERM".Upstream tests only
chroot("/") < 0and switches to false on anyfailure, logging
strerror(errno)for the operator rather than branching onit.
make_backups > 0 && !(flags & DEL_FOR_BACKUP) && (backup_dir || !is_backup_file(fbuf)).The omitted
DEL_FOR_BACKUPterm is what stops a deletion issued by thebackup machinery itself from recursing into another backup.
The retarget note is narrowed to what it actually covers, and gains an explicit
statement that this document has no section on 3.5.0's confinement model at all
--confine-root,--insecure-linksand the new daemondirectives are owned by
docs/design/upstream-3.5.0-path-confinement-model.md,so absence from the compatibility table is not evidence of parity. That was the
reading most likely to mislead once the old blanket caveat came off.
cargo xtask citationspasses: 9029 citations across 5072 files, every onenaming a file rsync 3.5.0 has at a line that file has. As that gate prints
itself, it does not check whether a cited line says what the comment claims -
which is exactly the class fixed here, and why the two subsections were read
against the C rather than re-pointed arithmetically.