mpuchstein/studipsync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify dirs and since flag

Browse Source
This commit is contained in:
Matthias Puchstein
2025-11-14 22:28:26 +01:00
parent 50c74438a8
commit c12310efca
2 changed files with 9 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@@ -13,9 +13,9 @@
## Directory Layout & Data Files
- Config lives under `${XDG_CONFIG_HOME:-~/.config}/studip-sync/config.toml`. A `default` profile is created automatically and stores the `basic_auth_b64`, base URL, JSON:API path, download root, etc.
- State is cached in `${XDG_DATA_HOME:-~/.local/share}/studip-sync/state.toml` with per-profile sections for user/semester/course/file metadata.
- Downloads default to `${XDG_DATA_HOME:-~/.local/share}/studip-sync/downloads`, but you can override `download_root` in the config to point anywhere else. Each path segment is sanitized to keep names human-readable yet filesystem-safe.
- Config lives under `${XDG_CONFIG_HOME:-~/.config}/studip-sync/config.toml`. Override this with `--config-dir` if you want the config somewhere else.
- State is cached in `${XDG_DATA_HOME:-~/.local/share}/studip-sync/state.toml`; `--data-dir` only changes this location (and anything else the tool stores under data, such as the default downloads folder). Use this when you want the state cache on a different disk but keep the config where it is.
- `download_root` determines where files land. If omitted, it falls back to `<data-dir>/downloads`, so moving the data dir automatically relocates the default downloads. Setting `download_root` explicitly decouples it from the data dir. Each path segment is sanitized to keep names human-readable yet filesystem-safe.
## Getting Started
@@ -70,9 +70,9 @@ max_concurrent_downloads = 3 # placeholder for future concurrency control
| `init-config` | Write a default config template (fails if config exists unless forced). | `--force`, `--download-root` |
| `auth` | Collect username/password, encode them, and save them to the active profile. | `--non-interactive`, `--username`, `--password` |
| `list-courses` | List cached or freshly fetched courses with semester keys and IDs. | `--refresh` |
| `sync` | Download files for every enrolled course into the local tree. | `--dry-run`, `--prune`, `--since` *(reserved for future API filters)* |
| `sync` | Download files for every enrolled course into the local tree. | `--dry-run`, `--prune`, `--since` *(currently just records the user-provided timestamp; the API filtering hook is planned but not implemented yet)* |
Global flags: `--quiet`, `--debug`, `--json`, `-v/--verbose` (stackable), `--config-dir`, `--data-dir`, `--profile`.
Global flags: `--quiet`, `--debug`, `--json`, `-v/--verbose` (stackable), `--config-dir`, `--data-dir` (state + default downloads), `--profile`.
## Sync Behavior
@@ -83,7 +83,7 @@ Global flags: `--quiet`, `--debug`, `--json`, `-v/--verbose` (stackable), `--con
- List file refs via `/folders/{id}/file-refs`, normalize filenames, and ensure unique siblings through a `NameRegistry`.
- Skip downloads when the local file exists and matches the stored checksum / size / remote `chdate`.
- Stream downloads to `*.part`, hash contents on the fly, then rename atomically to the final path.
4. Maintain a set of remote files so `--prune` can remove local files that no longer exist remotely (and optionally delete now-empty directories).
4. Maintain a set of remote files so `--prune` can remove local files that no longer exist remotely (and optionally delete now-empty directories). `--since` is accepted for future incremental sync work and currently acts as an annotation only—no API filters are applied yet.
5. `--dry-run` prints planned work but never writes to disk.
## Development Notes