Url enhancement: support line and column addressing for more precise rg searches

[Cachey4467]

yazi --debug output

Yazi
    Version: 26.1.4 (3c39a326 2026-01-06)
    Debug  : true
    Triple : x86_64-pc-windows-msvc (windows-x86_64)
    Rustc  : 1.92.0 (ded5c06c 2025-12-08)

Ya
    Version: 26.1.4 (3c39a326 2026-01-06)

Emulator
    TERM                : None
    TERM_PROGRAM        : Some("vscode")
    TERM_PROGRAM_VERSION: Some("1.107.1")
    Brand.from_env      : Some(VSCode)
    Emulator.detect     : Emulator { kind: Left(VSCode), version: "", light: false, csi_16t: (0, 0), force_16t: false }

Adapter
    Adapter.matches    : Iip
    Dimension.available: Dimension { rows: 31, columns: 150, width: 0, height: 0 }

Desktop
    XDG_SESSION_TYPE           : None
    WAYLAND_DISPLAY            : None
    DISPLAY                    : None
    SWAYSOCK                   : None
    HYPRLAND_INSTANCE_SIGNATURE: None
    WAYFIRE_SOCKET             : None

SSH
    shared.in_ssh_connection: false

WSL
    WSL: false

Variables
    SHELL              : None
    EDITOR             : None
    VISUAL             : None
    YAZI_FILE_ONE      : None
    YAZI_CONFIG_HOME   : None
    YAZI_ZOXIDE_OPTS   : None
    FZF_DEFAULT_OPTS   : None
    FZF_DEFAULT_COMMAND: None

Text Opener
    default     : Some(OpenerRule { run: "code -g \"%s:%l\"", block: true, orphan: false, desc: "Edit with default editor", for: None, spread: true })
    block-create: Some(OpenerRule { run: "code -g \"%s:%l\"", block: true, orphan: false, desc: "Edit with default editor", for: None, spread: true })
    block-rename: Some(OpenerRule { run: "code -g \"%s:%l\"", block: true, orphan: false, desc: "Edit with default editor", for: None, spread: true })

Multiplexers
    TMUX               : false
    tmux version       : program not found
    tmux build flags   : enable-sixel=Unknown
    ZELLIJ_SESSION_NAME: None
    Zellij version     : program not found

Dependencies
    file          : 5.45
    ueberzugpp    : program not found
    ffmpeg/ffprobe: 8.0.1 / 8.0.1
    pdftoppm      : 25.07.0
    magick        : 7.1.2-11
    fzf           : 0.67.0
    fd/fdfind     : 10.3.0 / program not found
    rg            : 15.1.0
    chafa         : program not found
    zoxide        : 0.9.8
    7zz/7z        : program not found / program not found
    resvg         : program not found
    jq            : 1.8.1

Clipboard
    wl-copy/paste: program not found / program not found
    xclip        : program not found
    xsel         : program not found

Routine
    `file -bL --mime-type`: text/plain

Please describe the problem you're trying to solve

Intention

I think Yazi's content searching experience is not quite ideal compared to VS Code currently.
I looked at the attempts of #3346 and #1095. and I summarized our needs as follows:

• Show the matched line in the preview so you can tell if it’s the file you want
• Place the cursor on the matched line (or the words) when opening the file in the default editor so you can start editing right away
  And I find it impossible to solve this purely with a plugin, so we should tackle it step by step.

Would you be willing to contribute this feature?

• Yes, I'll give it a shot

Describe the solution you'd like

Solution

I’d break the solution down like this:

1. Yazi will transmit line information to the previewer and the opener while in search mode (transparent to user, purely a system design detail).
2. The previewers will be responsible for highlighting logic.
3. The openers will accept those parameters and behave accordingly.

With that in mind, it makes sense to extend Url to support steps 1 and 3. I suggest adding line and column fields to Url.

pub enum UrlBuf {
	Regular(LocBuf),
	Search { loc: LocBuf, domain: Symbol<str>, line: Option<usize>, column: Option<usize> },
	Archive { loc: LocBuf, domain: Symbol<str> },
	Sftp { loc: LocBuf<typed_path::UnixPathBuf>, domain: Symbol<str> },
}

// same as UrlCow and Url

My implementation focuses on extending the Url module so previewers can highlight precisely and openers can jump to the exact line/column.

Why this approach

1. Including line and column in Url just feels natural.
2. Url is a flexible part of Yazi; using it to carry search details to the previewer and opener keeps added system complexity minimal.
3. Minimal impact on other modules: Copy/Move/Delete/Tab/Folder can simply ignore the extra attributes.

Notes / Open question

Should we implement this as a unified feature, or distribute it among the Lua code for each previewer? If it's the latter, it will allow us to expand support for other file types in the future (e.g., PDF, where it would be page numbers instead of line numbers). This would make it easier to #1084, which supports searching in file types other than just text files.

I’m still unsure about the best way to handle step 2. The previewer could receive an appropriately offset position in the peek function, but we might want a new method to tell the previewer which line to highlight. Or we might want a single built-in highlighting mechanism.

We need to consider the worst-case scenario: if the offset is large, for example, if the first match is the last line of a 10,000-line file, highlighting will take a long time. How will we handle this?

This is a step 2 problem. I don't know if it is critical XD

I use --no-heading in rg.rs, so it shows matches inline instead of grouped by file.

Additional context

2026-01-07.02-26-12.mp4

WIP
Still buggy. Path display is kinda broken, and a few larger bugs that cause other issues

Checklist

• I have searched the existing issues/discussions
• The latest nightly build doesn't already have this feature

[sxyazi]

Thank you for looking into it!

I haven't thought through the design very deepy yet, but here are some initial ideas:

• Line and column numbers should be encoded as strings into Url::Search's domain. This can reuse the existing domain-parsing infrastructure instead of introducing extra work to handle separate line and column fields, and it keeps the URL compact to reduce memory usage.
• In the search command, specifically rg.rs, the line and column numbers should be encoded into the Url::Search's domain.
• line and column can be got from the Url's domain property in the code.lua previewer plugin, then passed to the ya.preview_code() API so the preview highlights the specific line/column. That means ya.preview_code() needs additional line and column parameters.
• The corresponding feature could later be extended to PDF search via rga and jump to a specific page in the pdf.lua previewer, but that doesn't need to be supported now to reduce the amount of work.

[Cachey4467]

• Line and column numbers should be encoded as strings into Url::Search's domain. This can reuse the existing domain-parsing infrastructure instead of introducing extra work to handle separate line and column fields, and it keeps the URL compact to reduce memory usage.

So, you mean something like:
search://keyword#row:col:2:2//root/Documents/reports/2023/summary.docx?

• line and column can be got from the Url's domain property in the code.lua previewer plugin, then passed to the ya.preview_code() API so the preview highlights the specific line/column. That means ya.preview_code() needs additional line and column parameters.

If we want the previewer to highlight the whole matched word (or sentence), wouldn't we also need to include the keyword's length to the on top of the line and column numbers? If the keyword itself is needed, what should we pass to the plugin: the length or the actual content

[sxyazi]

Yeah but it might look more like search://row1,row2,row3,...:2:2//root/Documents/reports/2023/summary.docx:

• For the search item, it may not need to include the search keywords, and only included in the search portal.
• We can support only highlighted lines and exclude columns initially to simply the workload.
• We need to consider cases with multiple lines: if rg returns several matching lines, users should be able to press J/K in search mode to jump to the next/previous matching line.
• The domain hasn't been formally standardized yet, so its contents can be adjusted as needed which allows more flexible trial-and-error.

[Cachey4467]

• We need to consider cases with multiple lines: if rg returns several matching lines, users should be able to press J/K in search mode to jump to the next/previous matching line.

My initial thought was actually similar to #1095 , where each match in the same file is treated as an individual entry. So, are you suggesting we keep the display as it is, but let users cycle through each match in the preview area using J/K?

[sxyazi]

Yeah that should be easier to implement, otherwise we'd have to find a way to support multiple files with the same name in the same directory, or append line/column numbers to filenames as identifiers, which would require changing all filename/path-related places to support it e.g. opening/renaming/updating files, etc., and community plugins might also need to be updated.

…

On Thu, Jan 8, 2026 at 1:25 AM Cachey4467 ***@***.***> wrote: *Cachey4467* left a comment (sxyazi/yazi#3521) <#3521 (comment)> - We need to consider cases with multiple lines: if rg returns several matching lines, users should be able to press J/K in search mode to jump to the next/previous matching line. My initial thought was actually similar to #1095 <#1095> , where each match in the same file is treated as an individual entry. So, are you suggesting we keep the display as it is, but let users cycle through each match in the preview area using J/K? — Reply to this email directly, view it on GitHub <#3521 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEFWFIGU2F5JP7NAQQZRUXL4FU6QPAVCNFSM6AAAAACQ3S6NLWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMJZHEZTGNRUHE> . You are receiving this because you commented.Message ID: ***@***.***>

[Cachey4467]

Yeah that should be easier to implement, otherwise we'd have to find a way
to support multiple files with the same name in the same directory, or
append line/column numbers to filenames as identifiers, which would require
changing all filename/path-related places to support it e.g.
opening/renaming/updating files, etc., and community plugins might also
need to be updated.
…

I’m currently trying this out in the rg.rs

tokio::spawn(async move {
	while let Ok(Some(line)) = it.next_line().await {
		// Parse "filepath:line:content" format
		let (filepath, line_num, column_num) = match parse_rg_line(&line) {
			Some(result) => result,
			None => continue,
		};

		let Ok(url) = cwd.try_join(filepath) else {
			continue;
		};

		// Convert to search URL and add line number as fragment
		let Ok(url) = url.into_search(&subject) else {
			continue;
		};

		// Add line number by reconstructing URL with fragment (column defaults to 1)
		let url_str = format!("{:?}#{}:{}", url, line_num, column_num);
		let Ok(url) = url_str.parse::<UrlBuf>() else {
			continue;
		};

		if let Ok(file) = File::new(url).await {
			tx.send(file).ok();
		}
	}
	child.wait().await.ok();
});

Basically, I’m forcing each match line to create a File with the line number embedded in the URL. The outcome is shown in the video. Are there any downsides to this?

[sxyazi]

That will make the filename `name#line:column`, which is a fake name that doesn't exist in the filesystem, rather than `name`. Do Yazi's built-in features work with that filename, for example, what happens when you press `r` to rename the file?

…

On Thu, Jan 8, 2026 at 2:43 AM Cachey4467 ***@***.***> wrote: *Cachey4467* left a comment (sxyazi/yazi#3521) <#3521 (comment)> Yeah that should be easier to implement, otherwise we'd have to find a way to support multiple files with the same name in the same directory, or append line/column numbers to filenames as identifiers, which would require changing all filename/path-related places to support it e.g. opening/renaming/updating files, etc., and community plugins might also need to be updated. … <#m_-9193839820016632558_> I’m currently trying this out in the rg.rs tokio::spawn(async move { while let Ok(Some(line)) = it.next_line().await { // Parse "filepath:line:content" format let (filepath, line_num, column_num) = match parse_rg_line(&line) { Some(result) => result, None => continue, }; let Ok(url) = cwd.try_join(filepath) else { continue; }; // Convert to search URL and add line number as fragment let Ok(url) = url.into_search(&subject) else { continue; }; // Add line number by reconstructing URL with fragment (column defaults to 1) let url_str = format!("{:?}#{}:{}", url, line_num, column_num); let Ok(url) = url_str.parse::<UrlBuf>() else { continue; }; if let Ok(file) = File::new(url).await { tx.send(file).ok(); } } child.wait().await.ok();}); Basically, I’m forcing each match line to create a File with the line number embedded in the URL. The outcome is shown in the video. Are there any downsides to this? — Reply to this email directly, view it on GitHub <#3521 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEFWFIFTCBSUD2G7K5ODMV34FVHUFAVCNFSM6AAAAACQ3S6NLWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOMRQGI2DAMZSHA> . You are receiving this because you commented.Message ID: ***@***.***>

[Cachey4467]

That will make the filename name#line:column, which is a fake name that
doesn't exist in the filesystem, rather than name. Do Yazi's built-in
features work with that filename, for example, what happens when you press
r to rename the file?
…

I did a quick check of the code.

// yazi-actor\src\mgr\rename.rs
fn empty_url_part(url: &UrlBuf, by: &str) -> String {
	if by == "all" {
		return String::new();
	}

	let ext = url.ext();
	match by {
		"stem" => ext.map_or_else(String::new, |s| format!(".{}", s.to_string_lossy())),
		"ext" if ext.is_some() => format!("{}.", url.stem().unwrap().to_string_lossy()),
		"dot_ext" if ext.is_some() => url.stem().unwrap().to_string_lossy().into_owned(),
               // I guess the name is from here? I haven't verified it yet.
		_ => url.name().unwrap_or_default().to_string_lossy().into_owned(),
	}
}

// yazi-shared\src\url\buf.rs
pub enum Url<'a> {
	Regular(Loc<'a>),
        // rename extract name from Loc. 
	Search { loc: Loc<'a>, domain: &'a str },
	Archive { loc: Loc<'a>, domain: &'a str },
	Sftp { loc: Loc<'a, &'a typed_path::UnixPath>, domain: &'a str },
}

It seems like Rename gets the filename from Loc so it’s not affected by extending the domain field. Or am I missing something?

I’ve tested my current implementation: Search { loc: LocBuf, domain: Symbol<str>, line: Option<usize>, column: Option<usize> } and renaming seems to work fine.

[sxyazi]

You didn't store the line and column numbers in the filename (Loc) right? That should be fine for renaming, but many parts of the code assume there won't be two files with the same name in a single directory e.g. the reveal command - if there are two files named abc in the directory, how would you use reveal to locate the second one?

[Cachey4467]

You didn't store the line and column numbers in the filename (Loc) right? That should be fine for renaming, but many parts of the code assume there won't be two files with the same name in a single directory e.g. the reveal command - if there are two files named abc in the directory, how would you use reveal to locate the second one?

I'm not quite following the scenario with the reveal command. Could you give me some steps to try out so I can see if it’s actually broken?
Not sure how many other cases are affected, but maybe we can address it in the domain parsing logic.

[sxyazi]

reveal is used to locate a specified URL and move the cursor to that file.

A simple test is to left-click the second search result with the same filename in the search view and see whether the cursor moves to that file (the second one) or always stays on the first one.