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.

If you need installation help first, start with Installation. If you are here for editor integration, continue with Run mergeway-lsp manually.

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 mergeway-cli and mergeway-lsp from a release archive, Docker, Go, Nix, or source.

Run mergeway-lsp manually

Start the Mergeway language server, turn on logging, and understand its current capabilities.

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.