Hi, Stefan. Glad to see this! Changing the API syntactic form to an opaque struct + accessor functions sounds fine, as I mentioned on IRC. I see you've done that already.
As for the semantic changes, I want to help clarify our understanding of the high level 'shape' of merge scenarios. We need clear conceptual model in mind, in order to be able to suggest an understandable UI for merge conflicts. (We must continually be on the look out for conceptually simple ways to understand the system, and never accept that it has to be complex beyond understanding.) I've drawn a picture. The attached diagram 'merge corners 2.png' shows two branches, B1 and B2; let's say they are branch root directories, and they have children which are not shown. B2@60 is checked out into a WC. We are merging r30:50 from B1 to the WC. If this is an automatic merge, then B1@30 is the youngest common ancestor, both in reality and in what we tell the 3-way merge algorithm. That is true because an automatic merge requires that r10:30 from B1 is already merged to the target. Otherwise, this is a cherry-pick merge; B1@30 is an *assumed* common ancestor for the 3-way merge algorithm, while B1@10 is the *real* youngest common ancestor. Note that if we chose to use a 4-way merge algorithm for cherry-pick merges, aka 'variance-adjusted patching', such as the one implemented in our 'tools/diff/diff4', then we would pass it both the real YCA = B1@10 and also the source-left B1@30, as well as source-right and target. The three points marked in red (B1@30, B1@50, WC@working) are the main input 'corners' of the 3-way merge. Other revisions of interest are the WC base and the true YCA B1@10. The main point I want to make is that the WC base is not a high-level input to the merge. Rather, it is a point in the practical work flow that has to be negotiated to get to the desired logical endpoint (the WC working state). So where does this take us? I believe it's helpful to see two categories of conflicts: * conflicts between the two sets of version-controlled changes -- that is, the kinds of changes supported by the repository * inconsistent WC state -- for example, no file actually on disk where the working state metadata says there is a file, etc. (I don't even like to call these 'conflicts') Conflicts in category (1) are a result of the logical high-level merge operation. They are exactly the same conflicts that could occur if we were to implement an option to perform the merge on the server writing its result directly into a commit transaction. The most relevant data, in my opinion, are the three "corners" of the 3-way merge, followed next by the real YCA if different from source-left, and finally followed by the WC base state. The category (2) 'conflicts', on the other hand, are absolutely related to the WC state. The WC base state and working state are pretty much the only thing that needs to be shown. The merge itself is merely the reason why we found this inconsistency in the WC -- the merge is not the primary interesting thing about these. Thus, a conflict with reason 'svn_wc_conflict_reason_unversioned' for example is in category (2). By keeping these two categories conceptually separated, we can provide a clearer view of the relevant information. (Another thing I notice about the 'action' and 'reason' descriptions is they're documented as applying to an 'object' -- 'Object is unversioned', for example. The current merge system, and thus the conflict system, is mainly based on paths. In any tree change, one 'object' does not map cleanly to one path. This is a source of confusion.) Does that help a bit? - Julian Stefan Sperling wrote: > I would like to start transitioning away from svn_wc_conflict_description2_t > in public APIs and introduce a higher-level API to eventually replace it. [...] > Below is a sketch of an API I'd like to wrap around the > svn_wc_conflict_description2_t struct. > > The API uses terminology that I'd like clients to mirror in their user > interfaces. It breaks with some naming conventions that are misleading > or insufficient to describe complex conflicts (e.g. "yours/mine/theirs"). > It also tries to explain things in a way that prevents misunderstandings > of what the information returned by the API really means, so that SVN > client authors can make informed choices about how to present the information. > > The intention is to later extend this API to produce detailed data about > tree conflicts and other complex scenarios so that users can make more > informed choices about how to resolve conflicts. > See > http://mail-archives.apache.org/mod_mbox/subversion-users/201505.mbox/%3C20150520105235.GE4388%40jim.stsp.name%3E > for an example of what I'd eventually like to see at the conflict prompt. [...]
