Recover an Interrupted Command¶
A command that rewrites your working files can be interrupted before it finishes, by pressing Ctrl-C, by closing the terminal, or by the machine losing power. When that happens the workspace may be left part-way between two revisions, in an inconsistent state.
This affects fxv sync, fxv goto, fxv revert and fxv resolve. Nothing is lost when one of them is interrupted, but the workspace has to be returned to a consistent state before you can carry on working.
Recognize the state¶
Most commands refuse to run and tell you what happened:
$ fxv status
Error: A previous `fxv goto` was interrupted and this workspace is in an inconsistent state.
Was going from main.2 to main.30.
208,983 of 254,082 planned file change(s) applied, 45,099 remaining.
Run fxv resume to finish the command, or fxv resume --rollback to roll it back.
The report identifies the command that was interrupted, the revisions it was moving between, and how far it got. Scripts can detect this without parsing the message: the command exits with status code 98, and under --format json the same detail is available in the error payload.
Choose a direction¶
There are two options for recovering an interrupted command.
Continue finishes the interrupted command and arrives at the revision it was moving to. Choose this when you still want the result you originally asked for.
Continuing is the default, so fxv resume and fxv resume --continue do the same thing.
Roll back undoes the interrupted command and returns the workspace to the revision it was on before it started. Choose this when you would rather be back where you were.
Any local changes made between the interruption and the recovery are moved aside and committed as a draft revision rather than overwritten, so no work is discarded - like other commands in FlexVault, fxv resume is safe and will never discard changes.
If the recovery is itself interrupted¶
Interrupting a recovery is safe. It leaves the workspace in the same inconsistent state, and fxv resume picks up from wherever it stopped. You can interrupt and resume as many times as you need.
One thing to know about rolling back: it is not the exact inverse of the interrupted command, it is a new command planned in the opposite direction. Once a rollback has started, the original command can no longer be continued, and fxv resume will continue the rollback instead.
After a power loss¶
A power loss can leave files on disk in a state that a stopped process cannot, so a plain recovery may accept a file that was only partly written. In this case, prefer to use the --full option - this is typically not needed, and should be used only when the machine lost power or crashed.
--full re-checks and re-syncs every file in the interrupted command's plan, including those already recorded as finished. It reads far more data and takes considerably longer, so it is worth using only when you are concerned about the integrity of the workspace due to a power loss or crash.
If fxv resume cannot read the interruption¶
To continue or roll back, FlexVault needs the record the interrupted command left behind, which says how far it got. If that record is damaged, neither direction is available and fxv resume reports that it cannot act:
$ fxv resume
Error: A previous sync was interrupted and its journal cannot be read, so this workspace is in an inconsistent state.
D:\work\game\.fxv_workspace\state\sync_progress.rkyv (Internal error: Sync journal magic bytes do not match)
Neither fxv resume nor fxv resume --rollback can act on it. Run fxv doctor reset-sync to discard the journal and move the workspace to a known revision.
Recover by moving the workspace to a revision you choose, instead of trying to finish the interrupted command:
Without --revision, the reset moves the workspace to the latest published revision on the current branch, the same target fxv sync uses. Specify a different one with --revision main.456. The command shows what it is about to do and asks for confirmation first.
Resetting gives up the ability to continue or roll back the interrupted command, and that is all it gives up. Your files are snapshotted as a draft revision before anything is moved, so whatever the workspace held at the time of the reset stays recoverable through fxv history and fxv goto.
Use this only when fxv resume tells you it cannot read the interrupted command. While fxv resume still runs, prefer it, because it knows what the interrupted command was doing and the reset does not.