Skip to content
OpenVireoDeveloper
GitHub

Merge behaviour

How concurrent edits are combined, exactly.

When two devices change the same vault, a sync combines both sets of changes instead of keeping one and losing the other. It first merges each entry edited on both sides field by field, against the last version both had (the base copy): a field only one side changed takes that side’s value, and a field both changed takes the newer one and is reported in SyncResult.conflicts. Then it merges the structure (entries and groups added, moved or deleted), as specified below. Deletions are decided against the base too, not by the devices’ clocks: something deleted on one device is deleted everywhere unless another device changed it since the last sync, and then it stays. Most apps only need this paragraph; the rest is the exact specification.

mergeInto(source, target, mode) brings one database’s changes into another. Sync runs it twice (local → remote, then remote → local) after the field-by-field step (combineEntries), so both copies end up equal. The OpenVireo Qt client syncs the same files, so the observable result must match what it produces; packages/sdk/test/fixtures/merge-fixtures/ holds results recorded from the Qt client.

This document is the specification packages/sdk/src/merge/tree.ts is written from. It describes outcomes only.

  • Time of an entry or group: its last modification time, compared in whole seconds (KDBX files store seconds, so a copy that was saved and reopened has lost its milliseconds). A missing time counts as 0.
  • Location time: the time an item last changed parent. Compared in milliseconds, missing = 0.
  • Counterpart: the item with the same UUID anywhere in the target tree. The matching group for a source item is the target group that corresponds to the source item’s parent (the target root for the source root).
  • Copy of an entry: an entry with the same UUID and all of the original’s data (fields and their protection, attachments, times, icon, colours, tags, URL override, auto-type, custom data items, quality-check flag, previous parent), its attachments added to the target’s binary pool and its custom icon added to the target’s icons when missing there. A full copy also has copies of the history items (which never have history of their own); a plain copy has none.
  • Appending an item to a group detaches it from its current parent and adds it as the group’s last child.
  • History limit: the target’s historyMaxItems. Trimming keeps only the newest items when the limit is set and not negative.

Every action returns records {type, uuid?, title?, group?, details}. For an entry: its UUID, its Title and its parent group’s name. For a group: its UUID and its own name in group. For database-wide actions: only type and details. The records are listed in this order: tree walk, then deletions, then metadata.

Visit the source tree from its root. For each source group, handle its entries in order first, then its child groups in order. Each child group is handled (step 1.2) before its own contents.

  • No counterpart: append a full copy to the matching group. Record added, details "".
  • Counterpart exists:
    1. If the source entry’s location time is later than the counterpart’s and the counterpart is not in the matching group, append the counterpart to the matching group (its location time is not changed). Record moved for the source entry, details Previous location: <name of the counterpart's old parent>.
    2. Then compare times:
      • Counterpart older: replace it with a full copy of the source entry. The copy’s history is merged (§2) with the counterpart as the other side, and the copy is appended to the group the counterpart was in. Always record modified for the counterpart (its title and group as they were), details Add local modifications to new entry.
      • Same time or counterpart newer: merge the source entry’s history into the counterpart (§2). Record modified, details Add new modifications to existing entry, only if that changed anything.
  • No counterpart: create a group with the source group’s own properties (name, notes, icon, times, flags, custom data; no children), append it to the matching group, and give it the source’s location time. Add its custom icon to the target’s icons when missing. Record added, details Number of entries in group: <number of entries directly in the source group>.
  • Counterpart exists:
    1. If the source’s location time is later and the counterpart is not in the matching group, append it there and copy the source’s location time. Record moved, details Previous location: <the counterpart group's own name>.
    2. If the counterpart’s time is earlier than the source’s (whole seconds), update it and record modified with details listing what changed, joined by ", ", in this order:
      • Group name when the names differ (take the source’s);
      • Notes when they differ (missing = empty);
      • icon: if the source has a non-empty custom icon whose UUID differs from the counterpart’s, take it (Icon (UUID)) and add the icon image to the target when missing; otherwise, if the standard icon numbers differ or the counterpart has a custom icon, take the source’s number and clear the custom icon (Icon (Number));
      • Expiry time when the expiry times differ in whole seconds (take the source’s);
      • always Modification time (take the source’s).
  • Then walk the source group’s contents into its counterpart (or the new group).

Merging the history of entry S (other side) into entry T (the one being kept):

  1. Index history items by their time in whole seconds; when two share a time, the later one wins. Start from copies of T’s history items.
  2. Add each of S’s history items whose time isn’t in the index yet. If S is newer than T, S’s items also replace T’s items with the same time.
  3. If T is older than S, add a plain copy of T itself when its time isn’t present. If T is newer than S, add a plain copy of S itself when its time isn’t present. If they have the same time, add neither.
  4. Sort by time, oldest first.
  5. Decide whether this counts as a change by comparing the old and new lists from the newest end. With N = the history limit (10 if unset), the positions checked are the last N - 1 items of each list (so a limit of 0, 1 or a negative number never counts as a change). It is a change as soon as a position is filled in only one list or holds items that differ (§3).
  6. Only if it is a change: T’s history becomes the new list, trimmed to the history limit.

Two entries are equal when all of these match: UUID; the same set of fields (attributes, including the five standard ones, which count as present and empty when missing) with equal text and equal protection flags; attachments by name and content; tags; expiry (whether it expires and when, in seconds); icon (custom icon UUID, or the standard number); foreground and background colours; modification, creation, last access and location times in whole seconds; usage count; URL override; auto-type settings; custom data keys and values; previous parent group; and their histories, item by item.

Only in synchronize mode; keep-newer (the sync default) skips this step and keeps the target’s list of deleted objects as it is. Sync applies deletions against the base instead (§6).

  1. Go through the target’s deletion records, then the source’s, skipping any without a UUID or a time. The first record for a UUID decides what it refers to: an entry in the target, a non-root group in the target, or nothing there (then that first record is kept as is). A later record for the same UUID with an earlier time becomes the record used for that entry or group.
  2. Each entry with a record: if it was modified after the deletion time (milliseconds), keep the entry and drop the record. Otherwise remove the entry, keep the record, and record deleted with details Explicit deletion.
  3. Groups with a record, deepest first (a group waits while any of its child groups are still waiting): keep it and drop the record if it was modified after the deletion time or still contains any entries or groups. Otherwise remove it, keep the record and record deleted (Explicit deletion).
  4. If the resulting list (UUIDs and times, in order) differs from the target’s current list, it replaces it, recorded as metadata with details Changed deleted objects.
  1. Each custom icon of the source missing in the target is added: metadata, Adding new icon <uuid>.
  2. Database custom data. Its “last modified” time is the _LAST_MODIFIED item’s value when that parses as a date, otherwise the latest lastModified of its items. The source’s custom data is applied when the target has no _LAST_MODIFIED item, or when both times exist and the target’s is earlier. Applying it:
    • removes target items the source doesn’t have (Removed custom data <key> [<value>]), except the protected keys: _CREATED_, FDO_SECRETS_EXPOSED_GROUP, KPXC_REMOTE_SYNC_SETTINGS, KPXC_SYNC_GENERATION and every key starting with KPXC_BROWSER_;
    • copies every source item whose value differs (Adding custom data <key> [<value>]), except the generated keys _LAST_MODIFIED, KPXC_RANDOM_SLUG and KPXC_SYNC_GENERATION.

6. Sync: locations, deletions and the Recycle Bin

Section titled “6. Sync: locations, deletions and the Recycle Bin”

mergeDatabases(local, remote, base) adds three steps around the structure merge, as the Qt client’s SyncEngine::mergeDatabases does.

Locations. Before anything is merged, note for every entry both sides have the group and location time of the copy with the later location time in whole seconds (local wins a tie); both root groups count as the same group whatever their UUIDs. Right after the structure merge, put both copies in that group with that location time, without changing any modification times, and record moved with details Moved to where it was moved last when a copy changed group (fixing only the location time isn’t recorded). This keeps a move made on one device when another device edits the entry: replacing the older copy with the newer one would otherwise carry the newer copy’s group along with its fields. The Recycle Bin is an ordinary group here (recycling is a move); deleting for good follows the rules below. Groups don’t need this step, since the structure merge moves a group by its own location time and updates its name separately.

Deletions (only with a base). Before the structure merge, find each side’s pending deletions: a deletion record on one side for an entry or non-root group that is gone on that side and still on the other (the first record per UUID). After the structure merge has brought those items back, decide each one against the base; deletion and modification times play no part, so a wrong clock can’t decide:

  1. Entries: delete from both copies when the entry is in the base and every copy is in the same group as in the base with the same fields (§3); both copies then carry the record, recorded as deleted with details Deleted on another device. Otherwise keep it and drop every record for its UUID from both.
  2. Groups, deepest first: the same, where a group matches the base when its name, notes, icon and parent group are the same, and it is deleted only when every copy is empty.

Without a base nothing is deleted, and the records are left as they are.

Recycle Bin. The structure merge doesn’t carry the database’s Recycle Bin. After it, when the sides’ bins differ (an unset bin, or one whose group is missing, counts as none): a side without one takes the other’s; with two different bins, the one with the later recycleBinChanged in whole seconds wins (on a tie, the one whose UUID bytes sort first). On both sides the bin is set to the winner with the winner’s recycleBinChanged, and the other bin, unless the winner is inside it, has its entries and groups moved into the winner and is then deleted for good (with a deletion record). Recorded as metadata, Recycle Bin set from another device.