sync - moon

The moon sync command will synchronize the entire workspace and all projects by running configured sync operations. This ensures that all projects are in a consistent state and have their dependencies and tooling properly set up.

$ moon sync

How it works

The moon sync command performs the following operations:

Builds action graph - Creates a graph of all sync operations needed
Syncs workspace - Runs workspace-level sync operations
Syncs all projects - Runs project-level sync operations for every project
Executes pipeline - Runs all sync actions in topological order
Reports success - Displays confirmation when sync is complete

Sync operations can include:

Installing or updating dependencies
Generating configuration files
Setting up toolchains
Running setup hooks
Updating lockfiles

Arguments

This command takes no arguments.

Options

Inherits global options from overview:

--cache <mode> - The mode for cache operations.
--color - Force colored output.
--concurrency, -c - Maximum number of threads to utilize.
--log <level> - The lowest log level to output.
--quiet, -q - Hide all non-important terminal output.

Examples

Basic sync

Synchronize the workspace and all projects:

$ moon sync

Output:

▮▮▮▮ Syncing workspace
  ✓ Installing dependencies
  ✓ Updating lockfile

▮▮▮▮ Syncing projects
  ✓ app
  ✓ client
  ✓ server
  ✓ shared

✓ Synced the workspace and all projects

Sync with verbose logging

$ moon sync --log debug

Sync without cache

Force fresh sync operations:

$ moon sync --cache off

Quiet sync

Minimal output:

$ moon sync --quiet

When to run sync

You should run moon sync when:

After cloning a repository

When first setting up a workspace:

$ git clone repo
$ cd repo
$ moon sync

After pulling changes

When dependencies or configuration may have changed:

$ git pull
$ moon sync

After modifying configuration

When you’ve changed workspace or project configuration:

$ vim .moon/workspace.yml
$ moon sync

After adding dependencies

When you’ve added new dependencies to projects:

$ cd packages/app
$ npm install express
$ moon sync

In CI environments

The moon ci command automatically runs sync operations, but you can run it explicitly:

# GitHub Actions
steps:
  - name: Sync workspace
    run: moon sync

  - name: Run tasks
    run: moon run :build

Automatic syncing

In certain scenarios, moon will automatically run sync operations:

CI mode - When running moon ci, workspace sync always runs
First run - On initial workspace setup
Configuration changes - When configuration files are modified

Sync operations by tool

Different tools and platforms may perform different sync operations:

Node.js / npm / yarn / pnpm

Install dependencies from package.json
Update lockfiles
Link workspace packages
Generate node_modules structure

Rust / Cargo

Install dependencies from Cargo.toml
Update Cargo.lock
Build workspace metadata

Python / pip / poetry

Install dependencies from requirements.txt or pyproject.toml
Update lockfiles
Set up virtual environments

Go modules

Download dependencies from go.mod
Update go.sum
Tidy module dependencies

Configuration

Sync behavior is configured through:

projects in .moon/workspace.*
tools in .moon/workspace.*
node settings in .moon/toolchain.*
Project-specific configurations in moon.*

Comparison with other commands

Command	Syncs workspace	Syncs projects	Runs tasks
`moon sync`	Yes	All	No
`moon ci`	Yes	No	Yes
`moon run`	No	No	Yes

Troubleshooting

Sync fails with dependency errors

Ensure your package manager is properly installed:

$ node --version
$ npm --version

Sync is slow

Check if network connectivity is an issue, or use a local cache:

$ moon sync --log debug

Projects out of sync after sync

Try clearing cache and syncing again:

$ rm -rf .moon/cache
$ moon sync --force

Lockfile conflicts

Resolve lockfile conflicts manually and re-run sync:

$ git checkout --theirs package-lock.json
$ moon sync

Best practices

Run sync after configuration changes

Always sync after modifying workspace configuration:

$ vim .moon/workspace.yml
$ moon sync

Include sync in setup scripts

Add to your repository setup documentation:

## Setup

Clone the repository
Run `moon sync`
Start developing!

Use in CI pipelines

Ensure consistent state in CI:

steps:
  - name: Checkout
    uses: actions/checkout@v3

  - name: Sync workspace
    run: moon sync

  - name: Run tests
    run: moon ci

Commit lockfiles

Always commit lockfiles after syncing:

$ moon sync
$ git add package-lock.json yarn.lock pnpm-lock.yaml
$ git commit -m "Update lockfiles"

Overview

Core Commands

Project Management

Task Management

Code Generation

Utilities

Advanced

​How it works

​Arguments

​Options

​Examples

​Basic sync

​Sync with verbose logging

​Sync without cache

​Quiet sync

​When to run sync

​After cloning a repository

​After pulling changes

​After modifying configuration

​After adding dependencies

​In CI environments

​Automatic syncing

​Sync operations by tool

​Node.js / npm / yarn / pnpm

​Rust / Cargo

​Python / pip / poetry

​Go modules

​Configuration

​Comparison with other commands

​Troubleshooting

​Sync fails with dependency errors

​Sync is slow

​Projects out of sync after sync

​Lockfile conflicts

​Best practices

​Run sync after configuration changes

​Include sync in setup scripts

​Use in CI pipelines

​Commit lockfiles

Build docs developers (and LLMs) love