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 daemon isn’t running or serving this copy: see The daemon.
- The hub is unreachable: see Reaching the hub.
- Sending is held: see Accidental files and cleanup.
- History no longer matches the hive’s: rescue work in a new copy.
- Another sync error: follow the command’s hint, fix the cause, then run
musubi sync. If it persists, collect the logs.
“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:
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 logshows them), export it, and print the Git data directory:jj bookmark create rescue-1 -r <change> jj git export jj git rootIn 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 rescueInspect the rescued work with
jj logandjj diff. If changes are divergent because the hive rewrote their ancestors, rebase your work onto the hive’s versions before abandoning the old ones. Runmusubi syncand 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.