{"version":"2.1.242","anchor":"cloud-directory-sync-gains-git-and-tar-archive-engines-besid","canonical_anchor":"cloud-directory-sync-gains-git-and-tar-archive-engines-besid","heading":"Cloud directory sync gains git and tar-archive engines beside the per-file lane","tier":"soon","area":"Cloud Sessions","scope":null,"heads_up":null,"url":"https:\/\/changelogs.core-directive.com\/v\/2.1.242\/e\/cloud-directory-sync-gains-git-and-tar-archive-engines-besid","release_url":"https:\/\/changelogs.core-directive.com\/v\/2.1.242","markdown":"### Cloud directory sync gains git and tar-archive engines beside the per-file lane\n\nCloud file sync gains git-bundle and tar-archive modes, but you still sync file by file.\n\n**What**\n\nSyncing your working directory to a cloud session can now run through two new engines instead of shipping file rows one at a time. In a git checkout, each turn packs a snapshot commit into a bundle and exchanges it with the session; in a plain folder with no git root, an archive engine packs the tree into a gzipped tar. The per-file lane remains the fallback and the only always-on path, and the client-side selector is wired up while the cloud-side workers stay off unless separately enabled, so a plain `claude` in this build still syncs file by file.\n\n**Details**\n\n- `CLAUDE_CODE_DIR_SYNC_ENGINE` takes a comma-separated list and is also readable from settings; unset keeps the defaults, in which the git engine is allowed.\n- Accepted words are `git`, `archive` and `always-git` to select engines, `files` or `rows` to force the older per-file sync, and `none`, `off`, `0`, `false` or `no` to run no new engine. `always-git` additionally overrides the per-project memory that pins a directory to per-file sync.\n- An unrecognised word produces a single warning listing the vocabulary: \"known: git, archive, always-git (defaults), files\/rows (per-file sync), none\/off\/0\/false\/no (no new engine)\".\n- The variable is in the allowlist of environment variables forwarded to child processes, alongside `CLAUDE_CODE_DIR_SYNC_FFWD`; the older `CLAUDE_CODE_DIR_SYNC_OVERLAY` name has been dropped from that allowlist.\n- On the cloud side the git worker is constructed only when `CLAUDE_CODE_DIR_SYNC_GIT` is set and an async enabled check passes, and the archive worker only when `CLAUDE_CODE_DIR_SYNC_ARCHIVE` is set. With neither set nothing beyond the row lane runs, whatever `CLAUDE_CODE_DIR_SYNC_ENGINE` says.\n- Arming the git engine reads the repo layout, pins HEAD, and uses `git reflog` to spot a commit landing while the session was being created. Each failure falls back to per-file sync with its own message and reason: arm timeout, head moved, head unreadable, layout unsupported, arm failed.\n- A directory that fell back is remembered as a `dirSyncEngine` entry in `~\/.claude.json`, and the message tells you to remove that entry to retry. Repeatedly unacknowledged uploads stop the session and pin the directory to `\"files\"`, preceded by a softer one-off warning.\n- The archive engine ships its own tar writer and reader: pax headers for paths over 100 bytes, refusals for bad checksum, bad magic, unsafe path and unsupported entry, a gzip framing check, staged unpack directories, per-session state in `archive-sync.json`, a trash directory for peer deletes, and a 100 MiB archive cap.\n- New telemetry includes `tengu_dir_sync_folder_session`, `tengu_dir_sync_git_worker_armed`, per-turn git worker start and end events, and `dir_sync_origin` and `dir_sync_engine` properties.\n\n**Evidence**\n\n`archive-sync.json`, `tengu_dir_sync_folder_session`, `A commit was made here while the session was being created; this session syncs file by file instead of through git`, `known: git, archive, always-git (defaults), files\/rows (per-file sync), none\/off\/0\/false\/no (no new engine)`, `tengu_dir_sync_git_worker_armed`, `claude: fast-forward to the cloud session`, `remove this directory's dirSyncEngine entry from ~\/.claude.json`, `dir_sync_worker_archive_switch_on`, `; known: git, archive, always-git (defaults), files\/rows (per-file sync), none\/off\/0\/false\/no (no new engine)`\n\n- Area: Cloud Sessions\n- Names: `CLAUDE_CODE_DIR_SYNC_ENGINE`, `CLAUDE_CODE_DIR_SYNC_FFWD`\n- Tier: Nothing to try yet\n- Useful: 3\/5\n- Signal: 4\/5\n- Present in the build but not switched on"}