what are your thoughts on ripgrep's new support for hyperlinks?

[BurntSushi]

Main ask: Compile ripgrep from master with cargo build --release and try out its new support for hyperlinks. Hyperlinks using a file:// scheme are enabled by default, but you can do things like rg --hyperlink-format vscode ... to make ripgrep emit hyperlinks in a format accepted by VS Code. rg --help has documentation for the format accepted by --hyperlink-format. Does it work? Are the docs clear? What is sub-optimal? Just, in general, what is your experience? (NOTE: If you're using tmux, its latest release doesn't support hyperlinks. You'll need to build tmux from source and then add set-option -sa terminal-features ",*:hyperlinks" to your tmux configuration to make it work.)

Context: A while back, #665 was filed to request hyperlink support. @ltrzesniewski then put in a huge amount of work to get an initial implementation up in #2483. I did a little bit of polishing work and merged hyperlink support in #2610. From my perspective, there is potential for this feature to be a bit risky since it seems quite dependent on each individual application's support for hyperlinks. This is why, for example, things like --hyperlink-format vscode and --hyperlink-format textmate exist, since different applications have different hyperlink formats. The default on Unix is file://{host}{path} while the default on Windows is file://{path}. (It sounds like using {host} on Windows doesn't work quite well? That is something I'd love folks to try since I'm not a Windows user.)

Anyway, because of the integration specifics here, I'm interested in getting some feedback before the ripgrep 14 release. The most important thing is making sure the design is right, since it will be harder to change once it has been released. I would love folks to try it out and see what goes wrong!

UPDATE(2023-10-30): I'm currently planning for --hyperlink-format=none to be the default in the ripgrep 14 release. That is, hyperlinks won't be enabled by default. To get "default" support, one will be able to use --hyperlink-format=default. The reason for this is because it sounds like some environments bungle up hyperlinks (see an experience report in the comments below). I'd rather be a bit more cautious in the first release with hyperlink support, so I'm going to make them opt-in initially. It's plausible that subsequent releases will enable hyperlinks by default.

[wez]

I love to see this!

From my experience of trying to roll out the use of hyperlinks in a TUI in a big company, there are going to be people running terminal emulators that choke on them in a bad way. From a quick skim of #2610 it seems like you have an env var that will disable both colors and hyperlinks, but I would suggest that you also have an env var that will disable hyperlinks separately from colorization so that the people affected by that have the lowest friction way to bypass hyperlinks while retaining colorization; it will save you from pitchforks and fire-drills to restore their workflow!

I'll also share this discussion with some wezterm users that might be willing to try and give feedback.

[BurntSushi]

I'll also share this discussion with some wezterm users that might be willing to try and give feedback.

That would be great, thank you. <3

there are going to be people running terminal emulators that choke on them in a bad way

If the state of affairs is that loathsome, it might make sense to ship the next release with hyperlinks disabled by default. Otherwise, users will need to do --hyperlink-format none to disable hyperlinks while keeping colors. The NO_COLOR environment variable isn't something specific to ripgrep, just one that it respects via no-color.org.

I don't know of an analogous environment variable for only disabling hyperlinks, but I'm not sure I want to own the responsibility of creating one. :-)

[wez]

The majority of terminals and users will support it, it's just older installs/systems that won't. However, those users will likely have the least ability to "simply" upgrade.

I think the question is, what do you want to optimize for?

• Making something nice by default for the majority, at the expense of some weirdness in output for a minority. That weirdness will be difficult to nail down and figure out, so by the time they reach you to report it, they will likely be frustrated.
• Have things continue to be solid for everyone, at the expense of making it a bit harder to enable for the majority

There are good arguments either way: ultimately it's your call based on how you want ripgrep to be perceived!

an analogous environment variable for only disabling hyperlinks, but I'm not sure I want to own the responsibility of creating one. :-)

RIPGREP_NO_HYPERLINKS=1 as a simple way to bypass seems easy enough if you wanted to continue with enabled-by-default!

[yoav-lavi]

Just tested on macOS Sonoma (aarch64-apple-darwin) with WezTerm, a small sanity (build rg in release mode, ./target/release/rg =, click on one of the links) works correctly.

There's one thing I'd personally want to change: It opens in the OS default editor rather than $EDITOR, but it'd probably make more sense to handle that at the terminal level (cc @wez).

This feature is really awesome.

[wez]

re: $EDITOR, see wez/wezterm#3261 for how to setup a custom URI format and a handler to interpret it. If you tell rg to match that with --hyperlink-format, then it should be good?

[yoav-lavi]

That makes sense, can update when I'll get to try this out. Thank you @wez!

[BurntSushi]

@yoav-lavi On macOS, --hyperlink-format file://{host}{path} should be the default. Is that not the case for you?

As for which application gets opened, that's definitely outside the responsibility of ripgrep.

I'm unsure what to make of textmate and vscode not working. Perhaps that's a file handler issue as well.

[yoav-lavi]

@BurntSushi I'm pretty sure it was the default, the reason I also tested it explicitly was to show that file hyperlinks work with the flag and it's specifically those two cases that don't

[BurntSushi]

Gotya, thank you!

[Jackenmen]

Below's a wall of random thoughts while trying it out, I hope some of it is going to be useful.

Documentation-wise:
Formatting of the help for the parameter seems wrong - there are a lot of things wrapped in * as they maybe would in Markdown? It's unlike documentation for any other parameter so I'm guessing it's accidental (+ I'm not sure I've ever seen this kind of formatting in a terminal before):

The example in the first paragraph of the documentation you get from --help incorrectly mentions {file} instead of {path}.

When it comes to built-in formats, I think it could be helpful if what they correspond to was listed somewhere. I'm not saying that the exact value should be part of the no-breaking contract, just that it could be nice to know what it's doing, even if it may change slightly in some way in the future.

grep+ seems to use the wrong number of slashes in the protocol name part (grep+:/home/...) but I'm actually not sure what app it's for so maybe this is correct. I was also surprised to learn that people setup a custom subl protocol for their Sublime Text, I guess using this 'subl protocol' plugin, or maybe manually? I think that mentioning what it's supposed to be used with could be useful here.

Another thing is that I tried to just first go with my gut and try rg --hyperlink which was actually quite helpful as it pointed me to --hyperlink-format immediately but actually using --hyperlink-format doesn't give a particularly helpful message (i.e. I don't know what pattern to specify and have to look it up in --help after):

error: The following required arguments were not provided:
    <PATTERN>

I don't know if that's something fixable or if it's just how rg behaves for all arguments but I wanted to mention it, at least.

Behavior-wise:
Coming from hyperlinked_grep, the difference I notice is that I have to click on the line number if I want to open the file at the specific line - I can't just click anywhere on the line. For now, I'm not sure how to feel about this, it seems like it may be a little bit less convenient but I won't know until I use it for a bit. A nice little thing is support for the column number. Maybe it won't improve my experience in any way but still, nice to have that.

I will have to play with this in WSL (or Windows) too, maybe tomorrow... Sadly, Windows Terminal has some limitations with what it can do with hyperlinks but maybe I'll figure something out with a custom protocol handler since the Terminal Preview finally allows custom protocols to work too. Hopefully, nothing will break when using a preview version of Terminal 😄

Time to end this with a non-addressable piece of feedback, perhaps it will be helpful to someone else reading my comment - one thing that threw me off, coming from kitty's hyperlinked_grep, is that the default doesn't contain the line number column and so I thought that the documentation saying that hyperlinks are enabled by default is wrong since I couldn't see it by hovering over lines in the search results (this being doubled down by the fact that you actually have to hover over the line number, not the line). I absolutely think that this is the correct choice though since it's not really well-established what the format for specifying the line should be (file#line:column works with programs I use but it's probably not universal enough).

[ltrzesniewski]

Thanks for the feedback! 🙂

The example in the first paragraph of the documentation you get from --help incorrectly mentions {file} instead of {path}.

#2612 fixes this

When it comes to built-in formats, I think it could be helpful if what they correspond to was listed somewhere.

It's not exactly obvious, but they're listed in hyperlink_aliases.rs.

grep+ seems to use the wrong number of slashes in the protocol name part (grep+:/home/...)

That's strange, it's defined as grep+://{path}:{line}, are you sure you saw a single slash? There should have been three.

I think that mentioning what it's supposed to be used with could be useful here.

It uses https://github.com/inopinatus/sublime_url for subl (see the comment in hyperlink_aliases.rs), but maybe making it more apparent somehow would be useful.

Coming from hyperlinked_grep, the difference I notice is that I have to click on the line number if I want to open the file at the specific line - I can't just click anywhere on the line.

Some terminals (such as Windows Terminal) underline hyperlinks. Having the whole line underlined would look horrible.

Hopefully, nothing will break when using a preview version of Terminal 😄

Windows Terminal Preview works fine for me 😆

the default doesn't contain the line number column

It's because the default is the file:// scheme, which has no standard support for line/column numbers (ie, it doesn't use {line} in the pattern). Only headers (the file names) are hyperlinked in this case, as it would be confusing to hyperlink the line numbers otherwise.

file#line:column works with programs I use but it's probably not universal enough

That's a pattern used only by kitty AFAIK. Actually, ripgrep provides file://{host}{path}#{line} for kitty, since I haven't seen the file://{host}{path}#{line}:{column} syntax documented anywhere.

[BurntSushi]

@Jackenmen Thank you for the feedback! It's very helpful. In addition to what @ltrzesniewski said, I also touched up the docs a little bit. The * characters are there because the docs are written in asciidoc in order to be converted to roff for man pages, but the --help output just emits the raw asciidoc syntax under the presumption that it is supposed to be human readable.

[BurntSushi]

I've also added a note to the docs that says you can use the --debug flag to see what hyperlink format ripgrep is using.

[RossSmyth]

Testing on Windows Terminal, it seems to work

[ad-chaos]

On kitty, it works as well, Thank you!

It would be super nice if it hyperlinked the entire line rather than just the line number for ease of clicking.

Using ./target/release/rg -w --hyperlink-format kitty 'interpolator'

Using hg -w 'interpolator' (this is using hyperlinked grep kitten, which is just a wrapper around rg)

[BurntSushi]

Yeah I am not keen on making the entire line be hyperlinked. I'm also not keen on adding more options.

[ad-chaos]

as it would simply underline the whole ripgrep output

Is that a windows only problem?

Edit: Removed a bunch of irrelevant things

[ltrzesniewski]

Is that a windows only problem?

It doesn't depend on the OS, but on the terminal. Looks like kitty doesn't underline hyperlinks (until you hover over them maybe, like on your first screenshot), but I wouldn't be surprised if other Linux terminals underline them. And on macOS, looks like iterm2 also underlines hyperlinks.

[ad-chaos]

Ah, yes kitty only underlines when hovered.

[ad-chaos]

Also apologies, I didn't read jackenmen's post completely that mentioned this behaviour.

[akien-mga]

Tested with a few terminals on Linux (Mageia 9):

• konsole: ❌ (tested all --hyperlink-format presets)
• xterm: ❌
• kitty: ✔️ (with --hyperlink-format kitty)

[BurntSushi]

Thanks. It looks like xterm doesn't support hyperlinks. That list does claim Konsole does, and indeed, it looks like it was added three years ago. But they aren't enabled by default. It looks like you need to go through a sea of menus to find the mouse settings and then enable hyperlinks:

I did this and it seemed to do... something? It made it so I could hover over a link. But clicking them didn't work. And when I re-opened Konsole, hyperlinks weren't working at all despite the setting still being enabled.

(This is one of the reasons I dropped Konsole a few years ago. Configuring it is an utter nightmare, and I routinely ran into issues where its configuration just didn't stick or got reset somehow.)

[akien-mga]

Thanks! It's working for me after enabling "Underline files".

[Carreau]

It works on MacOS Ventura (13.4), iterm2 Build 3.4.20. Links are underlined by default which make it hard to read but that's an iterm2 problem.

I'd like to be able to view the format strings for each target of --hyperlink-format without looking at the source.

iterm2 already match some pattern and make them clickable to open files, and with hyperlink in rg, this bypass any configuration of patterns set by iterm. I guess it might break a couple of people with custom hooks in iterm when they upgrade, but it's a matter of reconfiguring and it will most likely be more accurate than iterm2. But you know everybody has their workflow so you can't please everyone.

IMHO the paragraph with the default format should be first. Most user will care about setting to one of default, file, grep+, kitty, macvim, none, subl, textmate, vscode, vscode-insiders, vscodium before customizing further.

[BurntSushi]

It's in a PR: #2614

[Carreau]

Oh, Sorry, I saw it, but probably skimmed it too fast.

[epage]

@Carreau if you don't mind me asking, did you happen to get an SCP dialogue?

I'm copying things in cargo as close to how ripgrep does it as I can tell and an iTerm2 user report that. My guess is that iTerm2 and cargo are disagreeing on the hostname. From rust-lang/cargo#12889:

For example, on mine (iTerm2), it breaks it so that instead of opening the file, it opens a dialog box asking for a username to SCP the file.

[Carreau]

No, not as far as I remember and not while testing right now. I get on cmd+hover file://Matthiass-Macbook-Pro.local/User/bussonniermatthias/<rest of the path>.

Also I'm not sure, but usually file:// have triple forward slashes, could that be the case ? Or maybe an iterm2 config I don't remember setting ?

[BurntSushi]

The triple forward slash happens when the hostname is absent. But it looks like the hostname is present in yours. Maybe the hostname is an issue here?

[fabian-thomas]

Currently, hyperlinks are not printed when a file is specified from command line (e.g. rg pattern /path/to/file), even when the hyperlink-format contains line and column. Should it be this way?

[BurntSushi]

Yes. When you search a file directly, ripgrep doesn't emit paths and the printer does not have access to one. So there's no way for it to emit a hyperlink. I may wind up considering this a bug that I ship ripgrep with, possibly to be fixed later, but it's an abstraction busting bug unfortunately. Sigh.

I'll at least add a clarifying note to the docs. Thank you.

[ptillemans]

Tested on Windows in Wezterm using powershell and the default settings work well.

[BurntSushi]

Thank you for responding!

[nbenitez]

I'm a Linux (Fedora) user with a licensed Sublime Text editor, and I can't get --hyperlink-format subl to work with a compiled ripgrep master :

Apparently under Linux ripgrep is using this protocol handler (which is advertised as being for MacOS) and has format subl://open?«arguments» while within Sublime Text we can install this subl protocol plugin which instead uses subl://absolute/path/to/file.txt:10

I would prefer that when using --hyperlink-format subl under Linux:
· If subl is in PATH, call it directly eg. subl "/path/to/file.c:300:50" to open in line 300 column 50.
· If not in PATH, call this subl protocol which uses subl://absolute/path/to/file.txt:10 format.

Thanks to Andrew and Lucas for working on this, this is really a productivity enhancer.

[BurntSushi]

I think the answer here is that since there is no official Sublime protocol handler, I'm just going to remove it from ripgrep. Users will need to write their own hyperlink format.

ripgrep will definitely not enter the business of opening editors directly and I do not want to add platform specific knobs that are designed to choose between different third party plugins.

Thank you for the feedback!

[lilydjwg]

Actually I've been using hyperlinks with ripgrep for a long time, with a wrapper script and the --json argument. I add hyperlinks on matches since those are what I'm looking at.