Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · App internals

Symbolic links

One rule for every file and folder the app reads or writes (settings, state files, backup, logs, export and import files):

  1. Follow links for reading and writing, absolute or relative, for single files and for whole folders (config/data folder, log folder).
  2. Never replace a link with a file. Atomic saves write the temp file next to the link's target and rename it over the target; the link stays. Corrupt-file recovery leaves the link in place and copies the target's content to <name>.corrupt next to the link.
  3. Never delete a link target. Log rotation of a linked gitoodo.log copies the content to .1 and empties the target; deleting rotated files removes only the link itself.
  4. Refuse where following is unsafe. A dangling link or a link loop is reported as an error ("points to ... which does not exist; nothing was written" / "loops back on itself"); nothing is created at the link's target. Logging swallows the error and retries later.

Implementation: crates/core/src/links.rs (resolve_link), used by store/fsutil.rs and logging/writer.rs. Export and import go through the same helpers, so the path returned by the file picker may be or contain a link.

Platforms#

  • Linux/macOS direct build: covered by unit tests (linked file, linked folder, relative, dangling, loop).
  • macOS sandboxed store build: a link outside the container only works if the user granted access to its target; the scoped-folder bookmark must be created for the resolved folder. Not verified on a device (documented only).
  • Windows: symlinks and junctions are followed by the OS for folders; file links are resolved by resolve_link. Creating them needs developer mode or admin rights, so the tests are Unix-only. Not verified on a device (documented only).
Docs version: dev