From 4fa6fff1a905b48a4e4a162bf7de30911c7053c4 Mon Sep 17 00:00:00 2001 From: Christian Kamm Date: Tue, 10 Apr 2018 10:31:12 +0200 Subject: [PATCH] Doc: Explaining conflict files and resolving them #6396 --- doc/conflicts.rst | 61 +++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 3 ++- 2 files changed, 63 insertions(+), 1 deletion(-) create mode 100644 doc/conflicts.rst diff --git a/doc/conflicts.rst b/doc/conflicts.rst new file mode 100644 index 000000000..b74be6ec1 --- /dev/null +++ b/doc/conflicts.rst @@ -0,0 +1,61 @@ +========= +Conflicts +========= + +.. index:: conflicts + +Overview +-------- + +The ownCloud desktop client uploads local changes and downloads remote changes. +When a file has changed on the local side and on the remote between synchronization +runs the client will be unable to resolve the situation on its own. It will +create a conflict file with the local version, download the remote version and +notify the user that a conflict occured which needs attention. + +Example +------- + +Imagine there is a file called ``mydata.txt`` your synchronized folder. It has +not changed for a while and contains the text "contents" locally and remotely. +Now, nearly at the same time you update it locally to say "local contents" while +the file on the server gets updated to contain "remote contents" by someone else. + +When attempting to upload your local changes the desktop client will notice that +the server version has also changed. It creates a conflict and you will now have +two files on your local machine: + +- ``mydata.txt`` containing "remote contents" +- ``mydata (conflicted copy 2018-04-10 093612).txt`` containing "local contents" + +In this situation the file ``mydata.txt`` has the remote changes (and will continue +to be updated with further remote changes when they happen), but your local +adjustments have not been sent to the server (unless the server enables conflict +uploading, see below). + +The desktop client notifies you of this situation via system notifications, the +system tray icon and a yellow "unresolved conflicts" badge in the account settings +window. Clicking this badge shows a list that includes the unresolved conflicts +and clicking one of them opens an explorer window pointing at the relevant file. + +To resolve this conflict, open both files, compare the differences and copy your +local changes from the "conflicted copy" file into the base file where applicable. +In this example you might change ``mydata.txt`` to say "local and remote contents" +and delete the file with "conflicted copy" in its name. With that, the conflict +is resolved. + +Uploading conflicts (experimental) +---------------------------------- + +By default the conflict file (the file with "conflicted copy" in its name that +contains your local conflicting changes) is not uploaded to the server. The idea +is that you, the author of the changes, are the best person for resolving the +conflict and showing the conflict to other users might create confusion. + +However, in some scenarios it makes a lot of sense to upload these conflicting +changes such that local work can become visible even if the conflict won't be +resolved immediately. + +In the future there might be a server-wide switch for this behavior. For now it +can already be tested by setting the environment variable +``OWNCLOUD_UPLOAD_CONFLICT_FILES=1``. diff --git a/doc/index.rst b/doc/index.rst index f0a8ff4f0..d5167110f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,6 +10,7 @@ Nextcloud Desktop Client Manual installing visualtour navigating + conflicts advancedusage autoupdate building @@ -17,4 +18,4 @@ Nextcloud Desktop Client Manual troubleshooting faq glossary - \ No newline at end of file +