How Sync Works

We have two states, “remote state” and “clone state”.

Remote state

The remote state is stored inside the .remote-state folder. It comprises all files’ history.

-- record remote-state:
file-history list history:

History

File history captures every modification to a file. It also included information about changes that happened due to merges, if an action happened to the “main branch” via merge from a CR, we store the CR where the change came from in the src-cr field.

-- record file-history:
caption filename:
file-edit-data list file-edit:

-- record file-edit-data:
caption or body message:
integer timestamp:
integer version:
optional string author:
option integer src-cr:
string operation:

Clone state

On the clone, the state contains the workspace information.

-- record clone-state:
workspace-entry list workspace:

-- record workspace-entry:
caption filename:
optional boolean deleted:
integer version:

Sync Scenarios

Given the current remote and clone state, a bunch of operations are there, which either print some output or update either the clone or remote state.

A file was updated locally, no changes on remote

We detect a file is updated locally by finding the version for every file in workspace.ftd, and then comparing the local file with the .history/<filename>.<version>.<ext>. If the content is different file is considered modified.

Say file is file.ftd, and its current version on remote is v1. On sync remote will get version (v1) and new content of file (file.ftd). Remote sees it’s own version of the file, let’s consider it’s also v1, so remote computes v2, and stored the new content of the file.

Remote returns latest file.v2.ftd content, and clone stores it in .remote-state, and updates the .clone-state/workspace.ftd and file.ftd in workspace.

A file was updated locally, with non conflicting changes on remote

If file.ftd was modified by someone else in the meanwhile, and the remote state has already moved to v2, remote does a three way merge between v1 version of file.ftd as “base”, and v2 as “theirs” and the current content as “ours”.

In non conflicting state the file content is simply updated. Remote computes a v3, and returns the merged content to clone, clone adds it to .remote-state folder, and updates the workspace.ftd and file.ftd’s content in the workspace.

A file was updated locally with conflicting changes on remote

If on remote, v2 and our changes do not merge cleanly with v1 version as based, remote notifies the clone that the sync for that file failed. Remote sends the v2 version of file which clone stored in .remote-state folder. workspace.ftd and file.ftd in workspace are not modified. This conflict, then, can be resolved by clone using fpm resolve-conflict <file>.

Only a file with no known conflicts are sent to remote

Before sending a file we check if the file has known conflict. To do this we use the version in workspace.ftd and the content of file.ftd for that version as “base”, and the latest version of file.ftd in .remote-state as “theirs”, and the content of file.ftd in the workspace as “ours” and perform three way merge, and if the merge fails, we know there is conflict.

Deleting a file, no edits on remote case

If a file is deleted from workspace and if fpm rm <file> command has been run, this sets deleted in workspace.ftd entry, we send this information to remote on fpm sync, and our version number. remote will see our version numbers match, so remote will create a new version number to mark deletion of the file, and update the .remote-state/history.ftd. And the clone will delete the entry from .clone-state/workspace.ftd.

Deleted by us, edited on remote

If the file we deleted has been updated on remote, remote will see different version number, and return a conflict message along with the latest content of the file. Our conflict detector will spot that we have deleted a file corresponding to a version number in workspace.ftd that is no longer the latest version of that file, and treat is as conflict and not send it to remote on next fpm sync.

Edited by us, deleted on remote

Remote again see two different version numbers, on delete we increase the version number, and reject the changes, as delete and edit are not cleanly merge-abe using three way merge operation.

Clone will show the conflict message.