OSC-1717 draft spec

[stefanhaller]

This was created as part of the work that happens in #5732; broken out into its own PR to make it easier to comment on.

[stefanhaller]

Input from @scottchiefbaker from #5732:

1. In this new metadata mode lazygit (or whoever) emits an environment variable EMIT_OSC1717_METADATA = V1[,V2,…] when it's in select hunk/line mode.

Yes.

2. If a pager sees this environment variable it needs to output a "handshake" as the first part of it's output indicating what version of OSC1717 it understands? "\e]1717;1\e\"

Not what version it understands, but what version it actually uses in this output, based on what the env var requested and what the pager itself supports. Section 3 of the spec is very clear on that.

Note that my goal is to never need a v2 of the spec, so the handshake will hopefully stay a simple "I'm requesting v1 -> ok, I'll emit v1" forever.

3. Will each line of context (the lines that are NOT changing) need a OSC1717 record? In the case of d-s-f which does line-by-line output, every output line will have a record?

Yes. This is important because if you use lazygit with a very large context size, you might be looking at an entire page of context without any change line in sight; you still want to be able to select those and hit e on them, for example.

4. From section 6.1 "One record per region, at the region's start".

In a line-by-line pager like d-s-f, this means one record per output line, so in your example that would be 19. A side-by-side pager will combine two original diff lines into one output line, so this one line will carry two records, and the word "region" refers to sections within that one output line that render one or the other original diff line.

In section 4.3 it says "context, new line 10" but I think it would be more clear as "context, line 10" because it's not new.

"Old line" and "new line" refer to line numbers in the old file (before applying the diff) and in the new file (after applying the diff). In the git project they often call these pre-image and post-image. A context line can have different old line and new line numbers, so it is important to say that records for context lines carry the new line number. We were actually considering whether we should require them to carry both, but lazygit doesn't need the old line number, so we thought it might be simpler for the pager not to have to include the old one.

[dandavison]

How about simplifying the env var name to OSC1717_METADATA?

I think leading with the important bit ("OSC1717") will be helpful for people scanning env output etc, and having the name be an imperative verb is a bit unusual among env var names related to development environments; they're most often nouns. I think it's OK to leave it implicit that if its set, supporting pagers should honor it.