project-data

Keep code in git, keep loose project data (PDFs, job postings, any local files that give a coding agent context) in a cloud-synced folder — gitignored, backed up, editable in Finder like a normal folder, and in sync across machines.

Each data folder in the repo is a symlink into <sync-root>/project-data/<repo-name>/<folder>, where <sync-root> is your Dropbox, iCloud Drive, Syncthing, or any provider under ~/Library/CloudStorage.

Install into a project

From the repo root:

curl -fsSL https://raw.githubusercontent.com/flo-kn/project-data/main/install.sh | bash

With explicit folders (otherwise a single data/ folder is used):

curl -fsSL https://raw.githubusercontent.com/flo-kn/project-data/main/install.sh | bash -s -- job-postings cover-letters

This vendors setup-data.sh into ./scripts/ (so fresh clones need nothing but the sync client installed), writes a starter .datadirs, ensures the folders are gitignored, and creates the symlinks. Existing real folders are moved into the sync location automatically. Commit scripts/, .datadirs, and .gitignore afterwards.

New machine

1. Install and sign in to your sync client, let it finish syncing.
2. Clone the repo.
3. scripts/setup-data.sh — data is there.

CI / opting out

setup-data.sh no-ops (exit 0) when CI is set — GitHub Actions sets this automatically — or when PROJECT_DATA_DISABLE=1 is exported. It also no-ops when no sync service is found. Code should tolerate missing data folders.

Configuration

• .datadirs — one folder per line, # comments allowed; this is the source of truth for which folders are managed data. Every entry must be gitignored (the script refuses to link entries that aren't).
• PROJECT_DATA_ROOT=/path — override sync-root auto-detection (e.g. an external encrypted volume).
• scripts/install-hooks.sh — optional post-checkout hook that re-runs setup-data.sh so links self-repair.

Gotchas

• Gitignore patterns must not have a trailing slash. job-postings/ matches only real directories; once the folder becomes a symlink git would start tracking it. Use job-postings. The installer handles this.
• Pick one sync service per project and stick with it. Auto-detection prefers Dropbox over iCloud; machines on different services would sync to different clouds. Pin with PROJECT_DATA_ROOT if in doubt.
• iCloud/Dropbox eviction. Mark the project-data folder "available offline" so files aren't replaced by online-only stubs that tools can't read.