Search the docs

How Conflicts Are Handled

When data is used across sites that are far apart, several questions affect the end-user experience:

  • How fast will I see new files?

  • What happens if I modify the same file on two sites at the same time?

  • What if the sites are disconnected for an extended period?

These come down to how ownership and conflict resolution work. The Global File System is eventually consistent and does not support cross-site file locking, so it relies on conflict-resolution logic and on objectives to manage data across sites.

As introduced in Core concepts, an objective is Hammerspace’s mechanism for controlling where and how long file data is kept. Two objectives are central to conflict handling:

log-xfer-1-<time>

Retains a version of a file before it changes owner. File ownership is determined by the site that last wrote the file. Ownership matters when another site needs the data but has no local copy — it reaches out to the owning site and orchestrates mobility.

undelete-<time>

Preserves files for a set period after deletion, enabling quick recovery from accidental deletes.

GFS shares automatically apply a log-xfer objective when a share becomes replicated, to protect against data loss when ownership changes. (Documented behavior; ties to DOCS-46 / HS-26986.)

Scenario 1: the Same Filename Created on Multiple Sites at Once

If the same file is created or modified on multiple sites during the same replication interval (or while sites are disconnected), GFS automatically creates two or more versions: a site-local file with the original name, and an additional file representing each remote version.

In this example a file of a different size is created on each of three sites from a Linux client, with the share mounted under /global.

Command:

cd /global
dd if=/dev/urandom of=file bs=1024k count=1 conv=notrunc   # Site A (ID 0)
dd if=/dev/urandom of=file bs=1024k count=5 conv=notrunc   # Site B (ID 1)
dd if=/dev/urandom of=file bs=1024k count=9 conv=notrunc   # Site C (ID 2)

After the replication interval passes, ls -l at Site A shows the local file plus the remote versions, each renamed FILENAME[#S=SITE ID]:

Expected output (abbreviated to size, date, and name):

total 15360
1048576 Feb 28 00:44 file
5242880 Feb 28 00:44 file[#S=1]
9437184 Feb 28 00:44 file[#S=2]

The same filename exists on every site; the conflicting versions from other sites are renamed so the local file never suddenly changes name and remote writes never overwrite local content. To resolve a conflict, copy the renamed version over the original filename and delete the automatically named file if it is no longer needed.

If the file has an extension, the rename preserves it: report.docx becomes report[#S=1].docx, not report.docx[#S=1]. Confirmed live 2026-08-27.

Scenario 2: Writing to an Existing File on Multiple Sites at Once

Metadata replicates to all sites, but file data is replicated only when requested — explicitly through objectives or implicitly on access. By default the last writer wins when two sites write the same file within the same replication interval.

To protect against user mistakes, GFS can preserve previous file content through the log-xfer objective. Because site-ownership changes create additional copies (similar to undelete and versioning), those copies carry an expiration set by the objective. If snapshots are taken before the files are deleted, the files remain in the snapshots until the longer of the snapshot retention or the file expiration elapses.

Site-Ownership Objectives

The objective name sets how long retained versions stay in the live tree. When a retained file is copied, the retention does not travel with the copy.

  • log-xfer-1-hour

  • log-xfer-1-day

  • log-xfer-1-week

  • log-xfer-1-month

Retained files appear in .snapshot/current, each made unique by an appended timestamp and the originating site identifier. A full decode of these filenames is in The shared Object Storage Volume in depth.