Start with this copy

In the affected repository, run:

musubi status

This reads local state without contacting the hub or snapshotting files. It exits 0 even when reporting a problem, and its last sync report can be stale if the daemon has stopped. The hub passes work between machines; each machine’s daemon syncs its local copies with it.

Follow the symptom:

“The hub has all its work” means work jj has recorded reached the hub. It doesn’t include unsnapshotted file edits, or establish that another machine received it.

If work reached the hub but hasn’t arrived elsewhere, run musubi status on the receiving machine. musubi top shows all machines’ last reports; a sleeping machine will catch up when it reconnects. See Check syncing.

If recorded work arrived but the checkout is stale, run jj workspace update-stale. See When another machine rewrites your working copy.

Reaching the hub

Run musubi list to check the connection. For a remote hub, check ssh and the executable from this machine, replacing devbox with the hub’s ssh name:

ssh devbox true
ssh devbox musubi --version

If ssh fails or waits for input, fix that first. The daemon never prompts and uses jj-musubi’s own key with your ~/.ssh/config; a successful interactive login alone doesn’t establish that it can connect. If its key is refused, run musubi join --hub devbox interactively in the affected copy to authorize it again.

If ssh can’t find musubi, add its directory to PATH in ~/.zshenv or ~/.bashrc before any early return for non-interactive shells. Alternatively, set the absolute SSH command path.

On the hub’s machine, check that musubi hub is running and inspect its log. If it serves with --dir, its entry in ~/.ssh/authorized_keys needs command="musubi hub connect --dir <dir>" too. For a hub that stops at logout or reboot, see service setup.

For an incompatible protocol or a daemon running an older build, follow Upgrade jj-musubi. The hub and machines need the same release or source build. For a missing hive on a replaced hub, follow Replace or move a hub.

Once the cause is fixed, run musubi sync. The daemon also retries automatically; a large first sync can take time and shows progress in a terminal.

The daemon

Run musubi daemon start to resume background syncing, or musubi daemon install to start it now and at login. On Linux, the installed daemon stops at logout unless you run loginctl enable-linger. create, join and clone start the daemon without installing login startup.

If a running daemon doesn’t serve this copy, run musubi join here again. For a duplicate copy after a move, restore or state-directory change, follow Move, copy or restore a repo.

If it won’t start or answer, inspect the daemon log. Use the same socket setting in every shell; see Configuration. For a socket that disappeared, musubi daemon restart restarts it.

To pause background traffic while investigating, run musubi daemon stop. This pauses all copies on this machine. musubi leave attempts a final sync, even with --force; see Pause syncing or leave.

Joining is refused

musubi join matches this repo to a hive: the copies of one project known to a hub. Run musubi list to check the hub and hive names.

If several hives match, or history matches but remote URLs don’t, choose the intended hive with musubi join --hive <name>. This still requires shared history. Use musubi create to start a separate hive, or musubi clone <hive> <new-directory> to get a copy of an existing one. Clone needs a new or empty directory; it also avoids shallow-clone and object-hash mismatches.

A remote name must have the same fetch and push destinations across a hive. --hive doesn’t bypass that check. Give a different destination an unused name, for example jj git remote rename origin fork, then retry. Renaming does not release the old name’s binding. See Fetch and push.

A filesystem copy duplicates the original’s identity. Use musubi clone for another syncing copy; use musubi join --original for a move or restore only once the original is gone. See Move, copy or restore a repo.

If the first sync fails after joining or cloning, the repo is set up and the daemon keeps trying. Fix the reported cause and run musubi sync; don’t delete the repo to retry setup.

Accidental files and cleanup

A snapshot hold pauses sending while receiving continues. Inspect the held history without snapshotting files or contacting the hub:

musubi sync --outgoing

Follow Snapshot limits and cleanup to exclude accidental files, prune their snapshots, or approve wanted history. Restarting the daemon doesn’t clear a hold.

Before removing operations, cleanup snapshots current edits and deletions in the invoking workspace. If cleanup is refused, it discards no operations, but that snapshot may remain. Follow its hint to update a stale workspace or restore access to a missing one, then retry. If a workspace is gone and no longer needed, remove its entry with jj workspace forget <workspace>. If two workspace names share a path, restore their separate directories or forget the obsolete workspace. Otherwise try a smaller selection, or approve the inspected history only if you want all of it shared.

If the command says “cleanup finished, but workspace metadata could not be updated”, history was already pruned. Restore write access to the named workspaces’ metadata, then run jj status there and follow any recovery hint. Native jj recovery may restore discarded history. Inspect musubi sync --outgoing again and prune the newly reported operations if needed; the original operation ids may no longer exist. The history rewrite and metadata updates leave checked-out files untouched; the preceding snapshot follows jj’s normal colocated Git import/export behavior and may update checkout files.

To recover wanted files without approving held history, make a new copy with musubi clone <hive> <new-directory> and copy only the files you want into it. Don’t copy .jj or .git. Describe or commit the copied work with jj, then run musubi sync there. Keep the original until you’ve checked the wanted work on another machine. For whole commits, use the rescue below; fetching also brings ancestors, which may contain unwanted content.

Rescue work in a new copy

If the error says this repo’s history no longer matches the hive’s, retrying won’t help. This can happen after operations are abandoned while a copy is out of the hive, forgotten, or away before its first sync finishes. Keep the original repo: its work is still there.

Make a new copy with musubi clone <hive> <new-directory>. Bring across work since the last successful sync, or all wanted work if the first sync never finished. You can copy files as above, or transfer commits:

  1. In the original copy, choose the commits you need. If rescuing held history, check their ancestors for unwanted content before fetching; transfer only wanted files if you cannot safely bring whole commits. Give each tip a temporary bookmark (jj log shows them), export it, and print the Git data directory:

    jj bookmark create rescue-1 -r <change>
    jj git export
    jj git root
    
  2. In the new copy, fetch and track those bookmarks, then remove the temporary remote:

    jj git remote add rescue <the path jj git root printed>
    jj git fetch --remote rescue -b 'rescue-*'
    jj bookmark track 'rescue-*' --remote rescue
    jj git remote remove rescue
    
  3. Inspect the rescued work with jj log and jj diff. If changes are divergent because the hive rewrote their ancestors, rebase your work onto the hive’s versions before abandoning the old ones. Run musubi sync and check the work on another machine.

After checking the rescue, run musubi leave --force in the original copy. It keeps that repo and still attempts a final sync before leaving.

Report a problem

If a failure persists after following its hint, open an issue. Include the command and full error, musubi --version on the affected machine and hub, and the relevant daemon and hub logs.

For “the hub refused this machine’s work”, include both logs: the hub’s log identifies what it couldn’t accept. To continue working, use the new-copy rescue. If history stops matching without an operation abandon or a returning copy to explain it, report that too.