Three-way merge
How create and update fold new template output into a target folder without losing the user's edits, and why the base is rebuilt instead of stored.
The problem. A template wrote files into your folder, and then you edited them. Now the template has a new version. How do the new files land without wiping your edits?
The idea in two lines. Treat it like git: base is what the templates made last time, local is your folder now, incoming is what they make now. Merge local and incoming against base, file by file and line by line.
The one fact newcomers get wrong: the base is not stored anywhere. It is rebuilt every time, by running every template again at its saved version with its saved answers.
The picture
The diagram shows where each of the three file sets comes from, and where the result goes:
flowchart TD
S[".cyan_state.yaml<br/>versions + answers"] -->|replay old versions| B["base<br/>(rebuilt)"]
S -->|run new versions| I["incoming"]
F["your folder"] -->|read, minus gitignored| L["local"]
B --> M{{"git merge<br/>in a temp repo"}}
L --> M
I --> M
M -->|delete dropped files,<br/>write the rest| FA worked example, file by file
The running example is the folder ./shop, made with atomi/web:5. You added a line to README.md and a file notes.md. Version 6 of the template adds a badge line and stops making old.txt.
Here is the folder before and after cyanprint update ./shop:
- .cyan_state.yamlweb:5 and its answers
- notes.mdyour own file
- old.txtmade by web:5
README.mdyou added the Run lineshow file
# shop Run: pnpm dev
- .cyan_state.yamlchangedweb:6 added to history
- notes.mdkeptonly you added it
- old.txtremovedonly the template dropped it
README.mdchangedboth changes keptshow file
 # shop Run: pnpm dev
Step through the merge to see what each set holds at each moment:
- Rebuild the base
Replay web:5 with the saved answers. Nothing old is read from disk.
README.md # shopold.txt presentnotes.md absent - Read local
Walk your folder, skipping gitignored files, .git/ and the state file.
README.md # shop + Run: pnpm devold.txt presentnotes.md your file - Build incoming
Run web:6 with the same answers.
README.md badge + # shopold.txt absentnotes.md absent - Merge with git
base is the first commit; local and incoming are two branches; rename detection at 50%.
README.md badge + # shop + Run: pnpm devold.txt deletednotes.md kept - Delete, then write
Delete what local has and merged does not, write the merged set, save a new history entry.
README.md writtenold.txt removed from disknotes.md untouched
If you and the template change the same line, nobody asks you. The file is written with git's conflict markers:
<<<<<<< ours# shop (internal)=======# shop store>>>>>>> theirs
The real code
Here is the merge itself, in the order it runs, from the real code:
- lines 144-152A temp repo starts from base; current and incoming branch from it.
cyancoordinator/src/fs/merger.rs:144-152rust // Create temporary repository with base VFSlet (repo, temp_dir) = self.create_temp_repo(base)?;// Commit the base statelet base_commit = self.commit_all(&repo, "Base state")?;// Create branches for current and incomingrepo.branch("current", &repo.find_commit(base_commit)?, false)?;repo.branch("incoming", &repo.find_commit(base_commit)?, false)?; - lines 230-233Rename detection is on, with the threshold the caller sets (50 for create and update).
cyancoordinator/src/fs/merger.rs:230-233rust // Set up merge options with find_renames enabledlet mut merge_opts = git2::MergeOptions::new();merge_opts.find_renames(true);merge_opts.rename_threshold(self.similarity_threshold); - lines 261-267On a conflict, the markers stay in the working folder; there is no prompt.
cyancoordinator/src/fs/merger.rs:261-267rust // Check if we have conflictsif repo.index()?.has_conflicts() {if self.debug {println!("⚠️ Merge resulted in conflicts");}// In case of conflicts, we keep the conflicts in the working directory - sulfone.iridium/cyancoordinator/src/fs/mod.rs:115-132Files in local but not in merged are deleted from your folder.
cyancoordinator/src/fs/mod.rs:115-132rust fn cleanup_deleted_files(&self,target_dir: &Path,local_vfs: &VirtualFileSystem,merged_vfs: &VirtualFileSystem,) -> Result<Vec<PathBuf>, Box<dyn Error + Send>> {let local_paths: HashSet<PathBuf> = local_vfs.get_paths().into_iter().collect();let merged_paths: HashSet<PathBuf> = merged_vfs.get_paths().into_iter().collect();let files_to_delete: Vec<PathBuf> =local_paths.difference(&merged_paths).cloned().collect();if !files_to_delete.is_empty() {self.writer.cleanup(target_dir, &files_to_delete)?;}Ok(files_to_delete)}
Rules worth knowing
- The base is only as true as the replay. If a template run does not give the same files for the same answers, the merge sees false edits.
- Deterministic state is not replayed. It is saved as an empty map, so a UUID or date made with the determinism helper changes on replay. Found while reading, not run.
- Every template in the folder is replayed on every run, not only the one being changed.
- Ignored files are outside the merge. A gitignored file is never deleted, and a template file at that path is written over it.
- Update stops if git is dirty, unless forced. Create does not check.
Why this way
- No stored base. Inferred: the state file holds only versions and answers, so the project stays small, and pinned versions plus the same answers can rebuild the base.
- git for the merge. Inferred: line merges, rename detection and conflict markers are what a developer already knows how to fix.