Skip to main content
On this page

Folded & Unfolded States

Folded

The Folded state represents the tutorial as a linear sequence of commits.
Each commit captures a step, forming a consecutive timeline from start → finish. This is the natural, reader-facing view of a Gitorial — and the environment where authors perform edits.

Folded View - VS Code

Unfolded

The Unfolded state represents the same tutorial as a set of full repository snapshots — one folder per step (e.g., steps/7/). Each folder reflects the state of the project at that step in time.

The Unfolded view is not edited directly; it acts as a structural shadow used for pull requests (and in the future step-based code reviews). Editors can use the UI to generate this view, which transforms the Folded timeline into a set of Unfolded steps/N/ folders. This process should be triggered whenever changes are made and the PR-ready data needs to be updated.

Unfolded View - VS Code

Mapping Rules

The relationship between the two states is deterministic and reversible:

Split view — left: Folded commit diff; right: corresponding Unfolded step/3 folder

  • Path mapping: A file at <path> in the Folded commit for step N maps to steps/N/<path> in the Unfolded view
  • File changes: modifications in Folded step N translate to diffs in steps/N/.
  • Adds/removes: file creation or deletion in Folded is mirrored in the corresponding Unfolded step.
  • Metadata: commit messages and supplemental data are stored in gitorial_metadata.json.

Metadata Bridging

Because the Unfolded view alone cannot reconstruct commit metadata, a companion file gitorial_metadata.json is introduced for each step:

interface GitorialMetadata {
  _Note: "This file will not be included in your final gitorial.";
  commitMessage: string;
}

This file is automatically generated and does not require manual edits.

Trade-offs

  • Simplicity vs. storage cost: duplicating the full repository per step simplifies reasoning but increases disk usage. Binary assets (e.g., images, videos) amplify this overhead. This is a known optimization target but intentionally deferred for early development speed.
  • Readable PRs vs. raw diffs: by annotating which step changed, reviewers see tutorial-aligned diffs instead of opaque multi-commit changes.