#Monorepo guide

rlsbl supports monorepo workflows via the rlsbl monorepo command family, which provides 10 subcommands for managing workspaces with multiple independently-versioned projects. A single workspace can contain any mix of the 14 supported release targets, all coordinated through one .rlsbl-monorepo/workspace.toml file at the repository root.

#Getting started

# Initialize a monorepo workspace
rlsbl monorepo init

# Add a project
rlsbl monorepo add --name mylib --path packages/mylib

# List projects
rlsbl monorepo list

# Show workspace status
rlsbl monorepo status

# Release a specific project from its directory
cd packages/mylib
rlsbl release patch

#workspace.toml format

The workspace file lives at .rlsbl-monorepo/workspace.toml and declares every sub-project in the repository. Each project is a TOML table in the [[projects]] array with a required path field and an optional name field that defaults to the directory basename. rlsbl validates this structure on load and raises clear errors for missing or malformed entries.

[[projects]]
path = "packages/mylib"
name = "mylib"

[[projects]]
path = "packages/cli"
name = "cli"

Fields per project:

#Workspace module

The workspace module handles discovery, loading, saving, and resolution of monorepo workspaces. It walks the directory tree upward to locate the nearest workspace.toml, parses the TOML structure into validated project entries, and writes changes back atomically using tomlkit to preserve formatting and comments.

#rlsbl.workspace

Workspace data layer for monorepo support handling discovery, loading, saving, and resolution of workspaces from workspace.toml config.

#find_workspace_root

def find_workspace_root(start_path='.')

Walk up from start_path looking for a .rlsbl-monorepo/workspace.toml.

Returns the directory containing .rlsbl-monorepo/, or None if not found.

#load_workspace

def load_workspace(root)

Read and validate workspace.toml, returning the list of project dicts.

Each project dict has at least 'path' (str) and 'name' (str, defaults to basename of path).

Raises FileNotFoundError if workspace.toml doesn't exist. Raises ValueError on invalid structure.

#save_workspace

def save_workspace(root, projects)

Write workspace.toml atomically using tomlkit for clean TOML output.

Preserves top-level sections, comments, and formatting from the existing file by reading it with tomlkit first and modifying the [[projects]] array in-place. Falls back to creating a new document when the file does not yet exist.

Creates .rlsbl-monorepo/ directory if it doesn't exist.

#resolve_project

def resolve_project(root, cwd='.')

Determine which project cwd is inside, returning its dict or None.

If multiple projects match (nested paths), returns the most specific one.

#Watch paths

Each project in a monorepo tracks changes independently based on its declared path in the workspace configuration. When you run a release command from within a project directory, rlsbl walks up the directory tree to find the workspace root, then matches your current directory against the registered project paths to determine which project you are releasing.

#Subtree publishing

Monorepo projects can be published to separate repositories using git subtree, which allows each sub-project to maintain its own standalone repository for consumers who do not want the full monorepo. The rlsbl monorepo sync command handles pushing subtrees to their configured remotes, keeping the split repositories in sync with the monorepo source of truth after each release.