What does "new_rev" mean in _sync metadata?

(Moved from https://github.com/couchbase/sync_gateway/issues/1624)

User hitales asked:

I found a document in couchbase with “new_rev”, and this document can not synchronize to couchbase lite forever, i don’t know why; one the lite side, the document is not in conflict list.

So, What does “new_rev” means in _sync? how can i resolve such document?

For example:
“new_rev”: “7-89c099875bdeb20239dc68c88ab07727”,
“rev”: “11-4fac5074eb7189ca1a836ae84bd8edf7”

The new_rev property is set when a new revision is added that isn’t the active revision for a document.

In this case, it looks like the document has at least two conflicting branches, and revision 7-89c099875bdeb20239dc68c88ab07727 was added to one of those branches. However, the already existing rev 11-4fac5074eb7189ca1a836ae84bd8edf7 is still the active revision.

I’m working to implement conflict resolution via Sync Gateway 2.7.4 at the moment and am hoping to get some clarification as this is the only documentation I seem to be able to find regarding this property.

The new_rev property is set when a new revision is added that isn’t the active revision for a document.

What does the word “new” in “new revision” actually mean? In other words, what is the exact criteria used to determine that one revision is “newer” than another? Is it the system clock of the source database in which each revision was created?

Consider the following actual Sync Gateway output:

"rev":     "3-8cdb214335c1d5e6cd2f0fe2f5b58caa"
"new_rev": "3-b92038509734173ef4b0b7838efa755f"

Why exactly was 3-8… placed in rev while 3-b… was placed new_rev?

Many thanks!

cc: @adamf

In general _sync metadata should be considered as internal data, and shouldn’t be used by anyone other than Sync Gateway. There aren’t any guarantees about availability or format of that metadata.

Having said that, in this scenario new_rev indicates that rev 3-b92038509734173ef4b0b7838efa755f was the most recent revision added to the document’s revision tree, but was not identified as the winning revision when comparing all non-tombstoned leaf revisions.