Getting Started with Mergeway

Introduce Mergeway workspace concepts, building blocks, and validation flow for new users.

This guide introduces the basic concepts and structure of a Mergeway workspace. It is intended for new users who want to understand how to set up and use Mergeway effectively. For runnable sample workspaces, see the examples directory in the GitHub repository.

A Mergeway workspace is just a folder with a few predictable parts. Knowing the vocabulary makes the CLI output easier to read.

Building Blocks

  • Workspace: Folder tracked in Git that contains mergeway.yaml, schemas, and optional objects. All commands run from here.
  • Schema: YAML/JSON that defines fields and references. Each file describes one entity.
  • Object: Optional data instances stored under data/.
  • Reference: A link from one schema or field to another (type: ref). Mergeway validates referential integrity.

Validation Flow

  1. Mergeway loads mergeway.yaml to locate schemas and records.
  2. Schemas are parsed and checked for required fields, types, and references.
  3. Records (if present) are validated against their schemas.

For field syntax and configuration options, see the Schema Format.

Install Mergeway CLI

Install the Mergeway CLI using a release download, Docker, Go install, or Nix.

Mergeway workspace set-up

Scaffold a Mergeway workspace and walk through the core commands end to end.

Schema format

Describe the Mergeway schema format and options for organizing schema files.