document conflict resolution

[aspiers]

(Originally posted by @aspiers in #112 (comment))

It would be great if lieer's conflict resolution mechanism was documented a bit more comprehensively. Currently, the docs say of gmi sync:

This effectively does a push followed by a pull. Any conflicts detected with the remote in push will not be pushed. After the next pull has been run the conflicts should be resolved, overwriting the local changes with the remote changes.

but there are a few unanswered partially answered questions here, e.g.

• How does lieer detect local changes which need pushing to the server?
  • Answer from this comment:

    a partial/incremental sync fetches the history in gmail since the last sync and applies those changes, it also pushes any changes since after a certain modification id in notmuch. there is no list of changes from notmuch, so those must be matched directly.

• How does lieer detect conflicts?
• How does lieer handle conflicts? E.g. if a mail is archived (removed from inbox) on the server and locally the unread label is removed, what happens? What about vice-versa, i.e. marked as read on server and archived locally?
  • Partial answer in my comment below.
• Was lieer designed with the hub-and-spoke use case of two machines both synchronising to gmail at the same time?

If I get answers then maybe I can find time to submit a PR to the docs.

[aspiers]

More questions, related not exactly to "normal" conflict resolution, but to resolution of differences due to changes in configuration:

The docs say:

If you change the ignored tags after the initial sync this will not update already synced messages. This means that if a change is made locally on an already synced message the previously ignored remote labels may be deleted.

What kind of ignored tags and change is this referring to? I'm guessing it's this situation:

• --ignore-tags-locally is set to prevent a tag foo from being synced from local to remote
• a mail has that tag foo set both locally and remotely
• foo is removed from the --ignore-tags-locally option
• the foo tag is removed from the local copy of the mail
• on next sync, the foo tag will also be removed from the remote copy

but I'm really not sure if that's right, or even why it would warrant a warning, because that feels like unsurprising and desired behaviour.

Similarly, this sentence confuses me:

Conversely, if a change occurs remotely on a message which previously which has local tags that were ignored before, these ignored tags may be deleted.

I'm guessing that's roughly the same situation except with --ignore-tags-remote and everything the opposite way around? But again, I don't see anything unsurprising or dangerous about that.

So maybe I'm misunderstanding.

[aspiers]

Potentially answering one of my own questions here. The docs say:

Any conflicts detected with the remote in push will not be pushed.

I think that's maybe referring to this code?

lieer/lieer/remote.py

Lines 668 to 675 in ad6dec2

	hist_id = int(gmsg["historyId"])
	if hist_id > last_hist and not force:
	print(
	"update: remote has changed, will not update: %s (add: %s, rem: %s) (%d > %d)"
	% (gid, add, rem, hist_id, last_hist)
	)
	self.all_updated = False
	return None

I'm wondering why that only activated for some of the messages in this run.

[aspiers]

Also realised this question

How does lieer detect local changes which need pushing to the server?

was previously answered here -- it uses notmuch's lastmod feature.