Local folder merge
When you connect a local folder to a server Project, devctrl brings that folder's
local-only work to the server and merges it with what is already there. You connect
a folder with ./devctl project add|sync|add-all|sync-all and a folder source.
The local work is:
- local branches;
- stashes;
- uncommitted and untracked work;
- the folder's native Claude Code sessions.
You see what would be merged and confirm it. Alternatively, a Project setting applies merges automatically.
Nothing local is written, and nothing on the server is overwritten.
The merge runs only where the devctrl local agent (client-agent) runs, and only for the folders you connected.
How it works
The connection. Connecting a folder records it in
.devctl/project-interchanges.json. The client-agent sees the folder through its existing read-only mount/project-policy/<host>/<project>. It also sees only that folder's Claude Code transcript directory, mounted read-only at/project-native/<host>/<project>/claude. SetDEVCTL_LOCAL_MERGE_CLAUDE=offbeforeproject add|syncto leave that mount out. Every registration takes part, including folders whose Exchange is a per-repository pair and legacy registrations; a legacy registration's checkout gets the same read-only mount, outside the Exchange mount generation.The plan.
- About every five minutes, the agent visits every repository Project that Core
lists for this client and fingerprints its connected folder: branch tips,
stashes,
HEAD, status, and transcript names and sizes. It also does this after every connect or sync. - Each pass logs one JSON line per Project,
local-merge.folder, with the outcome:planned(refs, sessions, upload bytes),nothing-to-merge,unchanged,skippedwith a reason (mode-off,disabled,not-mounted,not-git) orfailedwith a fixed code. Onelocal-merge.passsummary line follows. The lines hold counts, codes and IDs, never paths or content. - A connected folder that is not itself a Git checkout (a parent folder) merges its one direct child checkout whose origin is the Project's remote.
- A large folder stays mergeable. A bundle or transcript over the 2 GiB artifact
bound, or refs beyond 5000, are left out and shown in the plan as
skipped(too-large, with count and size); the rest of the folder still merges. Failures name the HTTP status (core-413),core-timeout,core-unreachable, orinvalid-responsewith the rejected field. - Only local-only work is sent. A branch whose commits the folder's
remote-tracking refs already contain is on the remote and is only counted
(
pushedRefs). A clean checkout has no snapshot. - When the fingerprint changes, it collects the folder read-only and sends Core a metadata manifest: refs, commits, counts, sizes and sha256 values. The manifest holds no content and no local path.
- Core checks that this client is linked to that Project and that the client and the Project have the same owner.
- Core plans the merge against its own state and its ledger. A newer plan replaces an older open one for the same folder.
- About every five minutes, the agent visits every repository Project that Core
lists for this client and fingerprints its connected folder: branch tips,
stashes,
The confirmation. In mode
confirm(the default) the Project owner reviews the plan and confirms or discards it:devctl local-merge list PROJECT devctl local-merge show PROJECT lmr-... devctl local-merge apply PROJECT lmr-... --plan-sha256 <sha> devctl local-merge discard PROJECT lmr-... devctl local-merge pending # every open merge (installation owner)In mode
autothe plan is confirmed when it is made.The upload. The agent uploads the plan's artifacts: one Git bundle and the transcripts. Core stores them by content and verifies size and sha256 while writing.
The import. Core plans again from the stored manifest.
- If anything changed, the merge is
supersededand the folder is planned again. - Otherwise one
local-merge.applycommand goes to the Project's checkout Host. The Host downloads and verifies each artifact, imports it by the rules below, and returns a receipt. Core records the receipt and the ledger.
- If anything changed, the merge is
What is merged
| Local work | On the server |
|---|---|
Local branch B |
Hidden ref refs/devctrl-import/<source>/heads/B |
Stash n |
refs/devctrl-import/<source>/stashes/<n>-<sha12>, the stash commit with its index and untracked parents |
| Uncommitted work | A snapshot commit at refs/devctrl-import/<source>/worktrees/main, plus the create-only branch refs/heads/imported/<source>/worktree-main |
| Claude Code transcript | Retained at <data root>/local-imports/<source>/claude/<native id>.<sha12>.jsonl on the Host |
<source> is <client id>-<folder key8>, so every connected folder of every device
has its own namespace.
How the snapshot is built:
- Its parent is
HEAD. Its tree isHEADwith the tracked changes and deletions applied, plus the untracked files that are not ignored. - It is built with a temporary index in a temporary bare repository that borrows
the folder's objects through
alternates. - Its dates come from
HEAD. An unchanged folder therefore yields the same commit, and merging it again is a no-op. - An untracked file over 20 MiB, or anything beyond 200 MiB in total, is skipped and counted.
How the bundle is built:
- It is thin. Commits that the folder's remote-tracking refs already contain are prerequisites and are not sent.
- If the server checkout lacks a prerequisite, the import fails closed with
prerequisite-missing, and the agent plans once more with a full bundle.
Merge rules
The server's own refs are never written: refs/heads/*, refs/remotes/*, tags,
HEAD, the index and the working tree. Each hidden ref is set by compare-and-swap:
| Server state of the ref | Outcome |
|---|---|
| absent | created |
| same commit | unchanged |
| an ancestor of the new commit | fast-forward (the old commit stays reachable) |
| anything else (rebase or reset) | diverged-kept: the old ref stays, and the new commit goes to <ref>@<sha12> |
| the commit is neither in the bundle nor on the server | missing |
imported/... branches are create-only. A different tip gets a -<sha12> suffix.
Transcripts are linked into place with an exclusive create. An identical file is
unchanged. A different file under the same name is an error, and the file stays
as it was.
A session the server already holds under the same native ID is
already-on-server.
Idempotency:
- The ledger is keyed by folder, item and content: the commit of a ref, or the sha256 of a transcript. A repeated merge of unchanged work is a no-op.
- Confirming needs the plan sha256.
- An applying merge is never queued twice. Its result is finalized from the authenticated Host result.
Settings
devctl local-merge settings PROJECT
devctl local-merge configure PROJECT --mode off|confirm|auto [--codex-sessions true|false]
codexSessions is stored, and it filters plans. Codex rollouts are not mounted
yet, because Codex stores them by date, not by folder.
Privacy and authorization
The local agent reads only:
- the connected folders, through read-only mounts;
- each folder's own Claude transcript directory.
It sends only those folders' Git objects and those transcripts. It never sends other folders, provider history or state databases, credentials, ignored files or absolute local paths.
Only a client linked to a Project, and with the same owner, can plan that Project's merge. Only that client can upload the artifacts.
Confirm, discard and settings are Project-owner routes; the server-user perimeter asserts ownership. The global list of open merges is for the installation owner.
A Host reads an artifact only while its own import that names it is in flight.
What is not merged
- Ignored files, credentials, and provider history and state.
- Remote-tracking refs, reflogs, hooks and
.git/config. - Uncommitted work in linked worktrees outside the folder. Their branches are merged.
- Claude sessions started in a subdirectory of the folder. Claude keeps those in another project directory.
Not yet included
- Codex rollouts.
- Attaching a retained transcript as a resumable server session. This means account-root placement with the cwd rewritten, as Overnight's portable restore does, plus a sibling worktree workspace on the imported branch.
- An attention notice for a new plan.
- The TUI view.