conflict. (This takes as input the ``last_downloaded_uri``
field from the directory entry of the changed ``foo``.)
3. Set the ``mtime`` of the replacement file to be *T* seconds
- before the current local time.
+ before the current local time. Stat the replacement file
+ to obtain its ``mtime`` and ``ctime`` as stored in the local
+ filesystem, and update the file's last-seen statinfo in
+ the magic folder db with this information. (Note that the
+ retrieved ``mtime`` may differ from the one that was set due
+ to rounding.)
4. Perform a ''file replacement'' operation (explained below)
with backup filename ``foo.backup``, replaced file ``foo``,
and replacement file ``.foo.tmp``. If any step of this
step 4c will cause an ``IN_CREATE`` event for ``foo``.
However, these events will not trigger an upload, because they
are guaranteed to be processed only after the file replacement
-has finished, at which point the metadata recorded in the
-database entry will exactly match the metadata for the file's
-inode on disk. (The two hard links — ``foo`` and, while it
-still exists, ``.foo.tmp`` — share the same inode and
+has finished, at which point the last-seen statinfo recorded
+in the database entry will exactly match the metadata for the
+file's inode on disk. (The two hard links — ``foo`` and, while
+it still exists, ``.foo.tmp`` — share the same inode and
therefore the same metadata.)
.. _`magic folder db`: filesystem_integration.rst#local-scanning-and-database
When synchronizing a file that has changed remotely, the Magic Folder
client needs to distinguish between overwrites, in which the remote
-side was aware of your most recent version and overwrote it with a
-new version, and conflicts, in which the remote side was unaware of
-your most recent version when it published its new version. Those two
+side was aware of your most recent version (if any) and overwrote it
+with a new version, and conflicts, in which the remote side was unaware
+of your most recent version when it published its new version. Those two
cases have to be handled differently — the latter needs to be raised
to the user as an issue the user will have to resolve and the former
must not bother the user.
this change as a conflict whenever they already have a copy of the
file.
+Conflict/overwrite decision algorithm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
Now we are ready to describe the algorithm for determining whether a
download for the file ``foo`` is an overwrite or a conflict (refining
step 2 of the procedure from the `Earth Dragons`_ section).
the directory entry metadata for ``foo`` in Bob's DMD (this field
may be absent). Then the algorithm is:
-* 2a. If Alice has no local copy of ``foo``, classify as an overwrite.
-
-* 2b. Otherwise, "stat" ``foo`` to get its *current statinfo* (size
- in bytes, ``mtime``, and ``ctime``).
+* 2a. Attempt to "stat" ``foo`` to get its *current statinfo* (size
+ in bytes, ``mtime``, and ``ctime``). If Alice has no local copy
+ of ``foo``, classify as an overwrite.
-* 2c. Read the following information for the path ``foo`` from the
+* 2b. Read the following information for the path ``foo`` from the
local magic folder db:
- * the *last-uploaded statinfo*, if any (this is the size in
+ * the *last-seen statinfo*, if any (this is the size in
bytes, ``mtime``, and ``ctime`` stored in the ``local_files``
table when the file was last uploaded);
* the ``last_uploaded_uri`` field of the ``local_files`` table
for this file, which is the URI under which the file was last
uploaded.
-* 2d. If any of the following are true, then classify as a conflict:
+* 2c. If any of the following are true, then classify as a conflict:
- * there are pending notifications of changes to ``foo``;
- * the last-uploaded statinfo is either absent, or different
- from the current statinfo;
- * either ``last_downloaded_uri`` or ``last_uploaded_uri``
+ * i. there are pending notifications of changes to ``foo``;
+ * ii. the last-seen statinfo is either absent (i.e. there is
+ no entry in the database for this path), or different from the
+ current statinfo;
+ * iii. either ``last_downloaded_uri`` or ``last_uploaded_uri``
(or both) are absent, or they are different.
Otherwise, classify as an overwrite.