Doc system test

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.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/composition
type
algorithm
rich
demo of the docs components (FileTree, Stepper, CodeWalk, diagram) on round 1 content
code
  • sulfone.iridium/cyanprint/src/run.rs
  • sulfone.iridium/cyancoordinator/src/fs/merger.rs
  • sulfone.iridium/cyancoordinator/src/fs/loader.rs
  • sulfone.iridium/cyancoordinator/src/fs/mod.rs
  • sulfone.iridium/cyancoordinator/src/state/services.rs

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| F
Where base, local and incoming come from

A 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:

./shop, before and after the update
Before (web:5 + your edits)
  • .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
    
After (web:6, merged)
  • .cyan_state.yamlchangedweb:6 added to history
  • notes.mdkeptonly you added it
  • old.txtremovedonly the template dropped it
  • README.mdchangedboth changes keptshow file
    ![build](badge.svg)
    # shop
    Run: pnpm dev
    

Step through the merge to see what each set holds at each moment:

Merging ./shop from web:5 to web:6
  1. Rebuild the base

    Replay web:5 with the saved answers. Nothing old is read from disk.

    README.md# shop
    old.txtpresent
    notes.mdabsent
  2. Read local

    Walk your folder, skipping gitignored files, .git/ and the state file.

    README.md# shop + Run: pnpm dev
    old.txtpresent
    notes.mdyour file
  3. Build incoming

    Run web:6 with the same answers.

    README.mdbadge + # shop
    old.txtabsent
    notes.mdabsent
  4. Merge with git

    base is the first commit; local and incoming are two branches; rename detection at 50%.

    README.mdbadge + # shop + Run: pnpm dev
    old.txtdeleted
    notes.mdkept
  5. Delete, then write

    Delete what local has and merged does not, write the merged set, save a new history entry.

    README.mdwritten
    old.txtremoved from disk
    notes.mduntouched

If you and the template change the same line, nobody asks you. The file is written with git's conflict markers:

README.md (a same-line clash)text
<<<<<<< ours
# shop (internal)
=======
# shop store
>>>>>>> theirs

The real code

Here is the merge itself, in the order it runs, from the real code:

sulfone.iridiumcyancoordinator/src/fs/merger.rs
  1. 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 VFS
    let (repo, temp_dir) = self.create_temp_repo(base)?;
    // Commit the base state
    let base_commit = self.commit_all(&repo, "Base state")?;
    // Create branches for current and incoming
    repo.branch("current", &repo.find_commit(base_commit)?, false)?;
    repo.branch("incoming", &repo.find_commit(base_commit)?, false)?;
  2. 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 enabled
    let mut merge_opts = git2::MergeOptions::new();
    merge_opts.find_renames(true);
    merge_opts.rename_threshold(self.similarity_threshold);
  3. 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 conflicts
    if repo.index()?.has_conflicts() {
    if self.debug {
    println!("⚠️ Merge resulted in conflicts");
    }
    // In case of conflicts, we keep the conflicts in the working directory
  4. 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.