feat(diff): open diff view at file:line on either side

Both entry points for the two-file diff view (CLI `--diff` and the
`:diff-open` command) already parsed the optional `file:line` or
`file:line:col` suffix via `parse_file`, but discarded the position.
Opening `hx --diff a.rs:42 b.rs:58` landed both panes at line 1.

Keep the position and apply it after each `editor.open`, using the same
pos_at_coords + set_selection + align_view pattern that the non-diff
file-open loop uses. In application.rs the work goes through a small
`apply_diff_positions` helper so both sides share one code path.

Integration tests cover the four cases that matter:

- `:diff-open a:3 b:5` positions both panes
- `:diff-open a:3 b` positions one pane, leaves the other at the top
- `:diff-open a b` with no suffixes keeps both at line 1 (regression guard)
- `hx --diff a:3 b:5` via `AppBuilder::with_diff` proves the CLI branch
  lands each cursor in its own pane

The CLI test was mutation-checked by commenting out both
`apply_diff_positions` calls and confirming the assertion fails.

Author: jcmuller

book/src/generated/typable-cmd.md

@@ -87,7 +87,7 @@
 | `:pipe`, `:\|` | Pipe each selection to the shell command. |
 | `:pipe-to` | Pipe each selection to the shell command, ignoring output. |
 | `:run-shell-command`, `:sh`, `:!` | Run a shell command |
-| `:diff-open`, `:diffs` | Open two files side-by-side in diff mode with aligned hunks. |
+| `:diff-open`, `:diffs` | Open two files side-by-side in diff mode with aligned hunks. Each path accepts a file:line or file:line:col suffix. |
 | `:reset-diff-change`, `:diffget`, `:diffg` | In a diff session: pull changes from the partner buffer. Outside a diff session: reset the diff change at the cursor position to the VCS base. |
 | `:diff-put`, `:diffput`, `:diffp` | In a diff session: push changes from the current buffer to the partner buffer at the cursor position. |
 | `:diff-off`, `:diffoff` | End the diff session for the current view. Both views continue as independent buffers. |

helix-term/src/application.rs

@@ -1,6 +1,6 @@
 use arc_swap::{access::Map, ArcSwap};
 use futures_util::Stream;
-use helix_core::{diagnostic::Severity, pos_at_coords, syntax, Range, Selection};
+use helix_core::{diagnostic::Severity, pos_at_coords, syntax, Position, Range, Selection};
 use helix_lsp::{
     lsp::{self, notification::Notification},
     util::lsp_range_to_range,
@@ -81,6 +81,27 @@ pub struct Application {
     theme_mode: Option<theme::Mode>,
 }
 
+fn apply_diff_positions(
+    editor: &mut Editor,
+    view_id: helix_view::ViewId,
+    doc_id: helix_view::DocumentId,
+    positions: &[Position],
+) {
+    if positions.is_empty() {
+        return;
+    }
+    let doc = doc_mut!(editor, &doc_id);
+    let selection = positions
+        .iter()
+        .map(|coords| Range::point(pos_at_coords(doc.text().slice(..), *coords, true)))
+        .collect();
+    doc.set_selection(view_id, selection);
+    if editor.tree.focus == view_id {
+        let (view, doc) = current!(editor);
+        align_view(doc, view, Align::Center);
+    }
+}
+
 #[cfg(feature = "integration")]
 fn setup_integration_logging() {
     let level = std::env::var("HELIX_LOG_LEVEL")
@@ -163,13 +184,16 @@ impl Application {
             if files.len() != 2 {
                 anyhow::bail!("--diff requires exactly two file paths");
             }
-            let (path_a, _) = &files[0];
-            let (path_b, _) = &files[1];
+            let (path_a, pos_a) = &files[0];
+            let (path_b, pos_b) = &files[1];
 
             let doc_a = editor.open(path_a, Action::VerticalSplit)?;
             let view_a = editor.tree.focus;
+            apply_diff_positions(&mut editor, view_a, doc_a, pos_a);
+
             let doc_b = editor.open(path_b, Action::VerticalSplit)?;
             let view_b = editor.tree.focus;
+            apply_diff_positions(&mut editor, view_b, doc_b, pos_b);
 
             let rope_a = editor.documents[&doc_a].text().clone();
             let rope_b = editor.documents[&doc_b].text().clone();

helix-term/src/commands/typed.rs

@@ -2592,16 +2592,28 @@ fn diff_open(cx: &mut compositor::Context, args: Args, event: PromptEvent) -> an
         bail!("Expected exactly 2 file paths: :diff-open file1 file2");
     }
 
-    let (path_a, _) = crate::args::parse_file(&args[0]);
-    let (path_b, _) = crate::args::parse_file(&args[1]);
+    let (path_a, pos_a) = crate::args::parse_file(&args[0]);
+    let (path_b, pos_b) = crate::args::parse_file(&args[1]);
     let path_a = helix_stdx::path::expand_tilde(path_a);
     let path_b = helix_stdx::path::expand_tilde(path_b);
 
     let doc_a = cx.editor.open(&path_a, Action::Replace)?;
     let view_a = cx.editor.tree.focus;
+    {
+        let (view, doc) = current!(cx.editor);
+        let sel = Selection::point(pos_at_coords(doc.text().slice(..), pos_a, true));
+        doc.set_selection(view.id, sel);
+        align_view(doc, view, Align::Center);
+    }
 
     let doc_b = cx.editor.open(&path_b, Action::VerticalSplit)?;
     let view_b = cx.editor.tree.focus;
+    {
+        let (view, doc) = current!(cx.editor);
+        let sel = Selection::point(pos_at_coords(doc.text().slice(..), pos_b, true));
+        doc.set_selection(view.id, sel);
+        align_view(doc, view, Align::Center);
+    }
 
     let rope_a = cx.editor.documents[&doc_a].text().clone();
     let rope_b = cx.editor.documents[&doc_b].text().clone();
@@ -4088,7 +4100,7 @@ pub const TYPABLE_COMMAND_LIST: &[TypableCommand] = &[
     TypableCommand {
         name: "diff-open",
         aliases: &["diffs"],
-        doc: "Open two files side-by-side in diff mode with aligned hunks.",
+        doc: "Open two files side-by-side in diff mode with aligned hunks. Each path accepts a file:line or file:line:col suffix.",
         fun: diff_open,
         completer: CommandCompleter::positional(&[completers::filename, completers::filename]),
         signature: Signature {

helix-term/src/main.rs

@@ -72,7 +72,8 @@ FLAGS:
     --log <file>                   Specify a file to use for logging
                                    (default file: {})
     -V, --version                  Print version information
-    --diff, -d                     Open two files side-by-side in diff mode
+    --diff, -d                     Open two files side-by-side in diff mode.
+                                   Each path accepts a file:line or file:line:col suffix.
     --vsplit                       Split all given files vertically into different windows
     --hsplit                       Split all given files horizontally into different windows
     -w, --working-dir <path>       Specify an initial working directory

helix-term/tests/test/diff_mode.rs

@@ -2,6 +2,195 @@ use super::*;
 
 use helix_stdx::path;
 
+#[tokio::test(flavor = "multi_thread")]
+async fn test_diff_open_applies_line_numbers_to_both_sides() -> anyhow::Result<()> {
+    let file1 = helpers::temp_file_with_contents("a1\na2\na3\na4\na5\na6\n")?;
+    let file2 = helpers::temp_file_with_contents("b1\nb2\nb3\nb4\nb5\nb6\n")?;
+
+    let mut app = helpers::AppBuilder::new().build()?;
+
+    test_key_sequences(
+        &mut app,
+        vec![
+            (
+                Some(&format!(
+                    ":diff-open {}:3 {}:5<ret>",
+                    file1.path().to_string_lossy(),
+                    file2.path().to_string_lossy()
+                )),
+                Some(&|app| {
+                    assert_eq!(1, app.editor.diff_sessions.len());
+                    helpers::assert_status_not_error(&app.editor);
+
+                    let norm1 = path::normalize(file1.path());
+                    let norm2 = path::normalize(file2.path());
+
+                    let cursor_line = |target: &std::path::Path| -> usize {
+                        for (view, _focused) in app.editor.tree.views() {
+                            let doc = &app.editor.documents[&view.doc];
+                            if doc.path() == Some(&path::normalize(target)) {
+                                let head = doc.selection(view.id).primary().head;
+                                return doc.text().char_to_line(head);
+                            }
+                        }
+                        panic!("no view for {}", target.display());
+                    };
+
+                    assert_eq!(
+                        2,
+                        cursor_line(&norm1),
+                        "file1 cursor should be on line 3 (0-indexed 2)"
+                    );
+                    assert_eq!(
+                        4,
+                        cursor_line(&norm2),
+                        "file2 cursor should be on line 5 (0-indexed 4)"
+                    );
+                }),
+            ),
+            (Some(":qa!<ret>"), None),
+        ],
+        true,
+    )
+    .await
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn test_diff_open_applies_line_number_on_only_one_side() -> anyhow::Result<()> {
+    let file1 = helpers::temp_file_with_contents("a1\na2\na3\na4\na5\na6\n")?;
+    let file2 = helpers::temp_file_with_contents("b1\nb2\nb3\nb4\nb5\nb6\n")?;
+
+    let mut app = helpers::AppBuilder::new().build()?;
+
+    test_key_sequences(
+        &mut app,
+        vec![
+            (
+                Some(&format!(
+                    ":diff-open {}:3 {}<ret>",
+                    file1.path().to_string_lossy(),
+                    file2.path().to_string_lossy()
+                )),
+                Some(&|app| {
+                    assert_eq!(1, app.editor.diff_sessions.len());
+                    helpers::assert_status_not_error(&app.editor);
+
+                    let norm1 = path::normalize(file1.path());
+                    let norm2 = path::normalize(file2.path());
+
+                    let cursor_line = |target: &std::path::Path| -> usize {
+                        for (view, _focused) in app.editor.tree.views() {
+                            let doc = &app.editor.documents[&view.doc];
+                            if doc.path() == Some(&path::normalize(target)) {
+                                let head = doc.selection(view.id).primary().head;
+                                return doc.text().char_to_line(head);
+                            }
+                        }
+                        panic!("no view for {}", target.display());
+                    };
+
+                    assert_eq!(
+                        2,
+                        cursor_line(&norm1),
+                        "file1 with :3 suffix should be on line 3"
+                    );
+                    assert_eq!(
+                        0,
+                        cursor_line(&norm2),
+                        "file2 without suffix should stay at line 1"
+                    );
+                }),
+            ),
+            (Some(":qa!<ret>"), None),
+        ],
+        true,
+    )
+    .await
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn test_diff_cli_flag_applies_line_numbers_to_both_sides() -> anyhow::Result<()> {
+    let file1 = helpers::temp_file_with_contents("a1\na2\na3\na4\na5\na6\n")?;
+    let file2 = helpers::temp_file_with_contents("b1\nb2\nb3\nb4\nb5\nb6\n")?;
+
+    let app = helpers::AppBuilder::new()
+        .with_diff()
+        .with_file(file1.path(), Some(helix_core::Position::new(2, 0)))
+        .with_file(file2.path(), Some(helix_core::Position::new(4, 0)))
+        .build()?;
+
+    let norm1 = path::normalize(file1.path());
+    let norm2 = path::normalize(file2.path());
+
+    let cursor_line = |target: &std::path::Path| -> usize {
+        for (view, _focused) in app.editor.tree.views() {
+            let doc = &app.editor.documents[&view.doc];
+            if doc.path() == Some(&path::normalize(target)) {
+                let head = doc.selection(view.id).primary().head;
+                return doc.text().char_to_line(head);
+            }
+        }
+        panic!("no view for {}", target.display());
+    };
+
+    assert_eq!(
+        1,
+        app.editor.diff_sessions.len(),
+        "--diff should create one diff session"
+    );
+    assert_eq!(
+        2,
+        cursor_line(&norm1),
+        "file1 cursor should be on line 3 (0-indexed 2)"
+    );
+    assert_eq!(
+        4,
+        cursor_line(&norm2),
+        "file2 cursor should be on line 5 (0-indexed 4)"
+    );
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn test_diff_open_without_line_numbers_stays_at_start() -> anyhow::Result<()> {
+    let file1 = helpers::temp_file_with_contents("a1\na2\na3\n")?;
+    let file2 = helpers::temp_file_with_contents("b1\nb2\nb3\n")?;
+
+    let mut app = helpers::AppBuilder::new().build()?;
+
+    test_key_sequences(
+        &mut app,
+        vec![
+            (
+                Some(&format!(
+                    ":diff-open {} {}<ret>",
+                    file1.path().to_string_lossy(),
+                    file2.path().to_string_lossy()
+                )),
+                Some(&|app| {
+                    helpers::assert_status_not_error(&app.editor);
+
+                    for (view, _focused) in app.editor.tree.views() {
+                        let doc = &app.editor.documents[&view.doc];
+                        if doc.path().is_none() {
+                            continue;
+                        }
+                        let head = doc.selection(view.id).primary().head;
+                        assert_eq!(
+                            0,
+                            doc.text().char_to_line(head),
+                            "unqualified :diff-open must leave both cursors at line 1 (0-indexed 0)"
+                        );
+                    }
+                }),
+            ),
+            (Some(":qa!<ret>"), None),
+        ],
+        true,
+    )
+    .await
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn test_diff_open_creates_session() -> anyhow::Result<()> {
     let file1 = helpers::temp_file_with_contents("one\ntwo\nthree\n")?;

helix-term/tests/test/helpers.rs

@@ -356,6 +356,13 @@ impl AppBuilder {
         self
     }
 
+    // Remove this attribute once `with_diff` is used outside the diff tests:
+    #[allow(dead_code)]
+    pub fn with_diff(mut self) -> Self {
+        self.args.diff = true;
+        self
+    }
+
     // Remove this attribute once `with_config` is used in a test:
     #[allow(dead_code)]
     pub fn with_config(mut self, mut config: Config) -> Self {