Gitorial Authoring - Infrastructure

Infrastructure

Authoring relies on a small set of robust mechanisms: Git worktrees, a Folded↔Unfolded sync engine, and metadata. Together they let authors iterate quickly while keeping the final tutorial a clean chain of commits.

Bend Git to Our Will

We keep two synchronized views of the same tutorial:

• Folded: the commit timeline (editing source)
• Unfolded: one folder per step (PR shadow)

Git worktrees let these views co-exist as separate checkouts that point at the same repository object database. This enables fast switching and deterministic rebuilds.

Sync engine

The sync engine does the mechanical work:

• Build Unfolded from Folded (on demand): materialize step-N/ folders by replaying commits
• Build Folded from Unfolded: transform per-step folders into a linear commit history (used when importing PR branches back to Folded)
• Track metadata: commit messages and future annotations live alongside content
• Detect impacts: identify downstream steps that may be affected by a change

Under the hood, the engine constructs diffs for each step-N/… and applies them to the corresponding Folded commit. Conflicts are surfaced early with precise context.

Operations overview

1. Initialize authoring
   • Create/attach two worktrees (Folded, Unfolded)
   • Generate gitorial_metadata.json where needed
2. Edit
   • Make edits in Folded; queue validations
3. Validate
   • Run tests/linters; verify Unfolded→Folded reconstruction
4. Create PR-ready structure
   • Generate Unfolded step-N/ folders from Folded; produce step-aware summaries and diffs

Implementation notes

• Worktrees avoid expensive cloning and allow independent index/state per view
• Large binary assets should be deduplicated using the VCS where possible
• Consistent line endings and formatting reduce noisy diffs across steps

Suggested visuals to embed