Support hyperlinks from pagers

[stefanhaller]

• PR Description

Allows to use delta --hyperlinks as a pager, which turns line numbers in the diff into clickable links that take you to the respective file. For VS Code users, I recommend to combine this with --hyperlinks-file-link-format="vscode://file/{path}:{line}" so that it jumps to the right line.

In addition, I added a few commits that replaces our old, manual ad-hoc handling of links in various places (status view, confirmation panels, information view) with the new hyperlinks feature, which cleans up the code a bit.

Fixes #3817.

• Please check if the PR fulfills these requirements

• Cheatsheets are up-to-date (run go generate ./...)
• Code has been formatted (see here)
• Tests have been added/updated (see here for the integration test guide)
• Text is internationalised (see here)
• Docs have been updated if necessary
• You've read through your own file changes for silly mistakes etc

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
Report missing for 58d74671	✅ ∅

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (58d7467)	Report Missing	Report Missing	Report Missing
Head commit (a0727ce)	49295	42224	85.66%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#3825)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

Footnotes

1. Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct. ↩

[dandavison]

Hi @stefanhaller, thanks very much! How do I try this branch out?

My lazygit config is

git:
  paging:
    colorArg: always
    pager: delta --light --paging=never --hyperlinks --line-numbers

and I'm doing make run. I can view diffs inside lazygit that are using delta, but the line numbers don't seem to be clickable.

[stefanhaller]

That looks about right, it's basically what I do when I develop. I don't have an idea why it doesn't work for you.

What terminal are you using? Mac's Terminal.app doesn't support OSC 8 hyperlinks, but I'm sure you know that.

[dandavison]

Hm. Just some very quick investigation -- I've confirmed that I am hitting some of the switch cases you added, such as stateOSCHyperlink, stateOSCWaitForParams, stateOSCParams. (Although, I see that I hit those lines whether or not I pass --hyperlinks to delta). I'm using Alacritty and hyperlinks work outside lazygit. It might turn out to be something silly on my end as this is the first time I have ever done anything involving building lazygit locally.

[stefanhaller]

Hitting switch statements can be misleading in go, the debugger tends to jump around a bit in weird ways. It's safer to set breakpoints in the bodies of the switch cases. Can you confirm that you are hitting line 228 in escape.go (the line ei.hyperlink += string(ch))? You should hit this when passing --hyperlink to delta, but not when you don't. Also, note that you need to quit and restart lazygit when you make changes to the config. (This will hopefully change soon.)

[stefanhaller]

Also, a common mistake is that people get the location of the config file wrong. Are you sure you are editing the right one? You can hit 1 e in lazygit to confirm this.

[dandavison]

the debugger tends to jump around a bit in weird ways. It's safer to set breakpoints in the bodies of the switch cases.

(Actually, I'm just writing log statements to a file)

Can you confirm that you are hitting line 228 in escape.go (the line ei.hyperlink += string(ch))?

Confirmed!

Confirmed the lazygit config file I'm editing is the right one.

I discovered the reason I was hitting the hyperlink code even when I did not have --hyperlinks in my lazygit config is that delta was (of course) using my own delta config in ~/.gitconfig. So with that confusion out of the way I see that I hit line 228 if and only if I pass --hyperlinks to delta in lazygit config.

I wouldn't want you to waste time on this, but of course happy to provide info if it is helpful to your development.

[dandavison]

OK, some more discoveries:

• Your hyperlinks do work for me in Wezterm! E.g. hover-over makes them underlined. However, I have to shift-click on them to open the URL. In contrast, in Wezterm outside lazygit I can click on them (and shift-click does not open the URL, it does something else)

• But they still do not work for me in Alacritty (whether I try click, or shift-click, or cmd-click). Outside lazygit in Alacritty, I cmd-click to open them.

(I'm using an M2 ARM Macbook)

[stefanhaller]

I wouldn't want you to waste time on this,

This is not wasted time, I want this feature to work for everybody, not just me.

I installed Alacritty to test this myself, and it doesn't work for me either. It works in the shell (e.g. when I do git -c core.pager="delta --hyperlinks" show HEAD), but not in lazygit. I wonder if this is Alacritty's problem, e.g. that it supports hyperlinks only for normal process output, but not for fullscreen apps? I'm not sure how to find out except by filing an issue on their repo. I'll see if I can find time to do that one of these days (unless you beat me to it... 😉)

Meanwhile, I thought more about the problem of the command-click being passed to lazygit too (the first bullet point in this comment), and I'm now considering handling normal (non-modifier) clicks on URLs inside of lazygit and launching the URL ourselves. This should fix that problem, plus it makes the URLs a bit more intuitive (like in a web browser), and it should also solve it for apps like Alacritty or Terminal.app that don't support hyperlinks for one reason or another. Of course, you don't see the underlines in that case, but maybe that's still better than not working at all. The downside is that when you command-click the link in a terminal that supports links, the URL will be opened twice, but that doesn't seem to be a problem for most types of links.

Curious what you think about that.

[stefanhaller]

I filed an Alacritty issue here: alacritty/alacritty#8129

[stefanhaller]

It turns out that you have to hold shift when clicking the link; I tested this and it works for me.

[dandavison]

Hm, that does not work for me. I thought it might be because I'm stuck on an old alacritty version, but I just tried alacritty built from main and shift-click still doesn't work for me. Then I thought it might be because I'm using tmux, but I'm finding that shift-click doesn't work for me for any combination of old/new tmux/no-tmux. I'll let you know if I discover anything more.

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
Report missing for 51e28fe1	✅ 96.00%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (51e28fe)	Report Missing	Report Missing	Report Missing
Head commit (782eb8d)	49280	42225	85.68%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#3825)	25	24	96.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

Footnotes

1. Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct. ↩

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.02%	✅ 96.00%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (fce6432)	49640	42485	85.59%
Head commit (a464aa9)	49591 (-49)	42453 (-32)	85.61% (+0.02%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#3825)	25	24	96.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

[dandavison]

What do you think about only showing the underline on-hover? I think it would look cleaner that way, and is what people are familiar with from web browsers (and is also how hyperlinks behave in native Wezterm).

[stefanhaller]

What do you think about only showing the underline on-hover? I think it would look cleaner that way, and is what people are familiar with from web browsers (and is also how hyperlinks behave in native Wezterm).

I don't like that much. Yes, it would look cleaner, but it would also be harder to use, as it wouldn't be obvious where the clickable links are. You, as the developer of delta, know that of course, but users might not, and so they would have to move the mouse over the whole window to find out what they can click on.

I'm not against adding additional highlighting on hover (as I mentioned here), to make it even more obvious that the link is clickable; but I don't find this essential, and it would be a lot of work, so I wasn't planning on working on that.

[dandavison]

OK, I'm definitely not claiming it's required in the first pass. Would a configuration option be a possibility?

I don't like that much. Yes, it would look cleaner, but it would also be harder to use, as it wouldn't be obvious where the clickable links are. You, as the developer of delta, know that of course, but users might not, and so they would have to move the mouse over the whole window to find out what they can click on.

I think I can counter that argument. Users only have to go through that "discovery phase" once; they'll soon discover the links due to the on-hover underline. This is similar to in a web browser, where the link underline does not appear until hover. Now, one might point out that in a web browser, links are typically styled with a different color to hint to the user that it's a link. But I believe that countering that point is the fact that the UI surface area of lazygit is vastly smaller than the UI surface area of the internet, and so even without styling hints, lazygit users will rapidly discover all the links. If we buy that argument then of course the advantage is that in all the 99.999% of the other times they are using the UI, they don't have to see the underlines until they hover.

[stefanhaller]

Interesting that you are so hung up on removing the underlines by default. I really like them being shown always, not only on hover. Curious what @jesseduffield thinks.

Would a configuration option be a possibility?

Not really. It would be a lot of work to implement underlining on hover, and I don't think spending that amount of effort is justified if there's only one user who doesn't want to see them.

[jesseduffield]

I agree with @dandavison on the underlines:

They look really noisy, and I find them harder to mentally parse than their non-underlined counterparts. I would also prefer an underline-on-hover approach. I agree with the argument that users will learn soon enough: I don't want a front-loaded benefit of discoverability to come at the ongoing cost of reduced legibility.

With that said, @stefanhaller says it's not easy to implement so I'm happy for us to just raise an issue for that and see if another developer is interested in doing that work.

[jesseduffield]

LGTM

[jesseduffield]

Are you using vscode-insiders because you personally use that? Or does that work for any vscode user? If it's the former we should assume the users aren't on the insiders edition.

[stefanhaller]

Ah yes, I was meaning to remove the -insiders but forgot. Fixed in 60d3b6a.

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00%	✅ 96.00%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (fce6432)	49640	42485	85.59%
Head commit (60d3b6a)	49591 (-49)	42443 (-42)	85.59% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#3825)	25	24	96.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

[stefanhaller]

I started working on the underline-on-hover feature. It will take a bit more time until all the edge cases are working (like the view changing its position under the mouse while the mouse is not moving, there are a lot of variations of these), but the basics are working.

However, I'm finding that the underline is way too subtle, it's really hard to see, especially on the grey numbers in the diff context lines. Any suggestions what to do instead? I tried reverse in addition (or instead), but that looks too much like a 90ies web page...

Hovered.Hyperlinks.mp4

(Just noticed that the underlines are always grey even for colored text. That must be a weird artefact of the screen recording, they have the right color on my screen.)

[dandavison]

I started working on the underline-on-hover feature. It will take a bit more time until all the edge cases are working (like the view changing its position under the mouse while the mouse is not moving, there are a lot of variations of these), but the basics are working.

Thanks for working on this @stefanhaller! Your video looks great to me, but maybe the video doesn't do a good job of faithfully communicating colors.

[dandavison]

Might be worth also mentioning that JetBrains IDEs support custom URL protocols. I believe (but have not recently tested) that examples are

hyperlinks-file-link-format = "idea://open?file={path}&line={line}"
hyperlinks-file-link-format = "pycharm://open?file={path}&line={line}"

But presumably similar exists for the other JetBrains IDEs (Go etc).

[stefanhaller]

Instead of mentioning these individually, I decided to link to your open-in-editor project, which I would hope will be kept up to date as other editors add their own URL schemes, so that we don't have to do this in two places. See afdd3b6.

[dandavison]

Hm, sorry, I don't think that linking to open-in-editor is the right thing to do! That project is very difficult to use , doesn't support Windows, and isn't necessary for users whose editors support their own URL protocol (VSCode, JetBrains IDEs, Zed, maybe others). It would be a confusing experience for visitors since the README basically suggests not to use it unless you really have to! It's also inactive, and I don't use it myself currently (my current solution is https://github.com/dandavison/wormhole but that's definitely not ready to link to, although you might be interested in it.)

[dandavison]

I think the right solution here is for me to add a "hyperlinks" section to the delta manual; I'll do that and post back here.

[dandavison]

Done: https://dandavison.github.io/delta/hyperlinks.html

[stefanhaller]

Very nice, thanks, that's a great writeup. I like the suggestion with the small python http server to solve this.

Linked to it in 01f65ed.

[stefanhaller]

Wait, this is all still too complicated. Users already have an editor configuration which is used when they press e in lazygit; they shouldn't have to do yet another editor-specific configuration orgy for this hyper-link feature. It should just use that config.

I added a commit (752ce3e) that makes it possible to set the hyperlink format to a lazygit-edit: URL, and it will recognize that and call the editor command. I think that's the best solution. (Documentation update in 7d53179.)

[dandavison]

That makes sense! (I'll have to look into what you do for lazygit-edit). I'm happy to have the new section for the delta manual in any case.

[dandavison]

If they don't use the lazygit-edit URL format, will lazygit pass the URL on to the operating system's standard protocol handling mechanisms (so that e.g. http:// issues an http request)?

[stefanhaller]

Yes.

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
Report missing for 61ae5e11	✅ 68.42%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (61ae5e1)	Report Missing	Report Missing	Report Missing
Head commit (bbd779b)	49648	42496	85.59%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#3825)	38	26	68.42%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

Footnotes

1. Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct. ↩

[jesseduffield]

still LGTM

[stefanhaller]

@jesseduffield @dandavison I made followup PRs for the highlight-on-hover: #3856 underlines them on hover as discussed here, but #3857 highlights them using the reverse attribute. Personally I prefer the latter, I think it looks better and is more ergonomic. Please try both and let me know what you think!

[Dagur]

I tried using this with the setting in the changelog i.e.

 git:
   paging:
     colorArg: always
     pager: delta --paging=never --line-numbers --hyperlinks --hyperlinks-file-link-format="lazygit-edit://{path}:{line}"

But the delta process get stuck at 100% CPU. Anyone else seeing that?