On Sun, Nov 24, 2024 at 5:25 PM Daniel Shahaf <d...@daniel.shahaf.name> wrote: > Don't leak implementation details into the API/CLI. In CLI terms, > applying a patch isn't a kind of merge, notwithstanding the libsvn_client > implementation details. > > In general, don't add --options that make a command do something > entirely different; rather, have each subcommand "do one thing and do it > well". > > The standard example for that is «svn switch --relocate», now known as > «svn relocate».
Hi, I'd like to discuss the command-line interface for working with xpatches in detail. Firstly, I'm going to explain the CLI I was initially suggesting: We have two basic operations in this area; Creation of xpatch files and their application onto a working copy. The creation step seems to be very similar to the plain `svn diff` command, because `svn diff` handles different targets greatly. I mean that it can differentiate either the working copy changes, changes made in any revision, two different trees, and any combination of the points above. I think that it's very familiar to the user to use the `svn diff` command for such an action, but changing the output format. I may also say that this command already accepts a bunch of different options, that change the output format. For example, `svn diff --summarize` and `svn diff --git`. In my opinion, adding another command that does everything the same as `svn diff`, but outputs the differences in xpatch format is a nice idea. I'll provide a list of different invocations options of `svn diff` that we will have: - svn diff > ../patches/something.patch - svn diff --summarize - svn diff --git - svn diff --git - svn diff --xpatch - svn diff --xpatch > ../patches/something.xpatch This seems to be a great and structured interface. Afterwards, I'm going to dig into the application of the xpatch files onto a working copy. This seems to be a bit more controversial than the creation step. I'm currently suggesting to use the `svn merge` command for this. If so, to apply an xpatch, the user should use commands like `svn merge --xpatch FILENAME [WCPATH]`. Then SVN will read that xpatch file from FILENAME and apply it over a working copy at WCPATH, or onto the current directory, if no WCPATH is given. For now, we haven't changed any behaviour from `svn merge`, except the `--xpatch FILENAME` argument added. Additionally, we are keeping most of merge's options such `--diff3-cmd`, `--force`, and we are using the same conflict resolution as one's in the merge. I mean we can do merge from different source, either URL in the same repository, URL in another repository, working copy path, or xpatch file, which is going to be added. I had another idea for such a command; I thought about simply adding commands such as `svn patch --xpatch`, but I didn't like it. It seems to be a bit confusing for me, because the word "patch" is duplicated. Also we would have to add a list of new options, which we are already having in `svn merge`. I'd add that these options may also confuse someone using `svn patch` to apply unidiff patches. I was also thinking about adding commands to view xpatch files, for example, viewing the summary or previewing them as unidiff, but I haven't designed it yet. Also, I think that GUI clients like TortoiseSVN may add dialog that will appear when the user opens an xpatch file. Then, they will be provided a list of changed paths (like in 'check for modifications' dialog), and by double-clicking to each file, they will get into diff-viewer. I think they will do it pretty well, if we implement it great and provide useful APIs. This is my point. If you or anyone else want to suggest any other ideas for the command-line interface, or leave a comment about one's I am suggesting, feel free to express them. It is very important to make a correct decision about it and have it accepted by the whole community. Want do add a few words about the leakage of implementation details into the API/CLI. I think it's great when the API functions works similarly to the command line interface. Of course they should not be exactly the same, since the command-line interface is made to be useful, while API should do exactly what it should do, so there could be several simplifications in the part of CLI, but if the differences we have between svn.exe and libsvn_client are getting minimal, the whole system would be simpler. > > 3. Optionally, we can also implement several commands to browse xpatch > > files using the command-line interface. For example, previewing them > > as unidiff or showing the diff-summary. > > > > In my opinion, the best way to save the changes is to write them to an > > XML file/stream (btw, this is why I would name this feature as > > "[x]patch"). > > Again, leaky abstraction. Please name the thing based on its API rather > than based on its implementation. There's a reason Air Force One's > callsign isn't "Biden One", you know :-) I had several candidates for the feature's name. Firstly, I was looking forward to name it as `bpatch`, because they are "binary" files, and can track "binary" files, but 1) git style patches are already named as `bpatch` somewhere and 2) it didn't sound pretty good for me. Then, I finally had a look on `xpatch`, due to XML format. Generally, it looks nice for me and I decided to keep it simple, without going deeply into naming, in order to save time. I am happy to hear any other voice about the name of the feature. This is an important part of it and this decision has to be done and accepted by the whole community. -- Timofei Zhakov
