sync

Synchronize the workspace and all projects

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:

1. Builds action graph - Creates a graph of all sync operations needed
2. Syncs workspace - Runs workspace-level sync operations
3. Syncs all projects - Runs project-level sync operations for every project
4. Executes pipeline - Runs all sync actions in topological order
5. 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

1. Clone the repository
2. Run `moon sync`
3. 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"