docs: describe how the mirror handles permissions

Explain why the group bits are set explicitly rather than left to the umask,
what is deliberately not touched, and that an existing mirror is repaired in
place rather than re-encoded.
This commit is contained in:
Emma Thorpe
2026-08-24 11:28:18 +01:00
parent 18b1bbbbd1
commit e3025c5d6a
+14
View File
@@ -55,6 +55,20 @@ Encodes are written to a temporary file and renamed into place, so an
interrupted run cannot leave a truncated MP3 that the next run mistakes for interrupted run cannot leave a truncated MP3 that the next run mistakes for
finished work. A lock file in the mirror root stops two passes overlapping. finished work. A lock file in the mirror root stops two passes overlapping.
### Permissions
Everything written into the mirror is made group-readable, and its directories
group-traversable, so the mirror can be read back by whatever serves it. Neither
writer does that unaided: the temporary file an encode renames into place is
created `0600` regardless of the umask, and a straight copy of an existing MP3
inherits the mode of a source file in a library this tool does not own. Only the
group bits are touched; whether the mirror is world-readable stays with the
umask, as does the ownership.
Mirror files written before this existed are topped up on the next pass. Their
mtimes are correct, so nothing else would revisit them — and they are not
re-encoded, only chmod'ed.
## Usage ## Usage
```sh ```sh