LEP: Git-style revision show command proposal

[theRTC204]

Summary

This proposal adds a Git-style lore revision show <revision> command that combines the outputs of lore revision info --delta and lore file diff into a single output similar to that of git show <revision>.

At present two distinct commands are required in order to get details of a specific commit.

• lore revision info --delta for the metadata and file-action summary
• lore file diff for the content of the changes

The current design complicates the implementation for consumers of the CLI/CAPI who wish to visualize the contents of a repository on a per-commit basis, such as a visual diff tool, IDE or engine integration. Furthermore, the current implementation of lore file diff makes it impossible to visually display the contents of the root revision in a Lore repository.

[ragnarula]

Hey thanks for this LEP. Could you please elaborate a bit more on what the use case for this is and why, besides the N~1 issue for the root revision, it's not ok to just call the two separate commands to get the info you need (info and diff).

I'm not sure adding a new command to do something similar which can already be composed is the right solution. I think too many variants of similar things is one of the failings of git.

[theRTC204]

I don't have a strong technical argument for a new command or even a combined command. There is no technical barrier to running the two commands either in the CLI nor for building tooling on top of the CAPI.

My motivation was in reducing the friction for adoption of Lore for Git users. Perhaps I got the wrong assumption, but it appears as though Lore has designs aimed around that philosophy already (.loreignore following the same pattern matching as .gitignore, for example)

Personally, I make use of git show fairly often, and it is convenient that it produces a complete result for the HEAD commit without need to specify a revision. With Lore I have to lore revision info then manually copy & paste both the signature & parent into a lore file diff --source <signature> --target <parent> (both are required if you don't have a clean working directory). The difference goes from typing 8 characters to all the way to ~34 plus copying & pasting two GUIDs and that count is just for the second of two commands necessary.

Git today
git show gives the revision, author, date, message & diff for the HEAD commit
git show <rev> same as above, for the target commit
git diff gives the diff of the working tree
git diff <rev~N> gives the diff between source and working tree
git diff ..<rev~N> gives the diff between working tree and target
git diff <rev~N>..<rev> gives the diff between source and target

Lore today
lore revision info gives revision, sig, parent, branch, date & message
lore revision info --delta same as above, plus only the A/M/D of the file names
lore file diff gives the diff of the working tree
lore file diff --source <rev~N> gives the diff between source and working tree
lore file diff --target <rev~N> gives the diff between working tree and the target
lore file diff --source <rev~N> --target <rev~N> gives the diff between the source and target

I had noted an alternative consideration in the proposal, which was adding an additional flag such as --patch into lore revision info's option flags, but I ruled it out because flags have discoverability traps and aren't really very intuitive for a lot of people in my experience.

All this being said, while writing this response it occurred to me that Git doesn't really have an analog to Lore's revision info that only shows revision, author, date, message without the diff. In that sense, outside of a syntax change maybe the correct proposal would be to add support for showing the diff into revision info would be the better approach.

[ragnarula]

Ok I understand the pain for sure and I've come around a bit.

I think your alternaive of something like lore revision info --patch would actually sit nicely along side lore revision info --delta for the case where you want the metadata and the patch.

Then theres the case where we want only a patch, no metadata. We already have revision diff which again outputs the file delta list, it could also have a --patch arrgument to that which makes it output a patch only.

@ajcarberry @mjansson wdyt?