[vim/vim] runtime(termdebug): Allow remote debugging over tty (ssh, wsl, docker ...) (PR #18429)

MiguelBarro

unread,

Sep 28, 2025, 3:17:15 PM (9 days ago) Sep 28

to vim/vim, Subscribed

The termdebug plugin doesn't work with gdbserver because is focus on tty. This plugin allows launching gdb connecting it via tty to the program windows.

This PR modifies it to allow using a remote tty device by launching the program window terminal remotely too. It automatically detects remoting if g:termdebug_config['command'] uses ssh or wsl (vim can access the sources directly on that case).

For other use cases (like docker) a g:termdebug_config['remote_windows'] allows customization.

This only works in prompt-buffer mode because termina-job mode (default) specifically creates a local tty window.

The PR provides g:termdebug_config['substitute_path'] entry to map remote to local files using the same strategy that gdb's substitute-path command.

Examples

ssh

In this case the netrw builtin plugin retrieves the sources automatically from the remote machine.

let g:termdebug_config = {}
let g:termdebug_config['use_prompt'] = v:true
let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb']
let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' }

wsl

In this case the Windows OS will use special UNC paths for the linux filesystem and mounts for the windows drives.

let g:termdebug_config = {}
let g:termdebug_config['use_prompt'] = v:true
let g:termdebug_config['command'] = ['wsl', 'gdb']
let g:termdebug_config['substitute_path'] = {
    \ '/': '\\wsl.localhost\Ubuntu-22.04\',
    \ '/mnt/c/': 'C:/' }

Note: the UNC path can be queried using wslpath tool.

You can view, comment on, or merge this pull request online at:

https://github.com/vim/vim/pull/18429

Commit Summary

7a1c123 Update source windows on stop event
3e4dd97 Update breakpoint management.
4310d49 Update debugee terminal set up
f76cea2 Update documentation
b7894ce Update testing

File Changes

(4 files)

M runtime/doc/tags (3)
M runtime/doc/terminal.txt (43)
M runtime/pack/dist/opt/termdebug/plugin/termdebug.vim (185)
M src/testdir/test_plugin_termdebug.vim (66)

Patch Links:

—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Sep 29, 2025, 5:12:56 AM (8 days ago) Sep 29

to vim/vim, Push

@MiguelBarro pushed 1 commit.

1f2435f Piggyback fix on gdb's job options. Must be reorder to work properly.

—
View it on GitHub or unsubscribe.
You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Sep 29, 2025, 8:15:00 AM (8 days ago) Sep 29

to vim/vim, Push

@MiguelBarro pushed 1 commit.

05d1cee Piggyback fix on gdb's job options. Must be reorder to work properly.

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Sep 29, 2025, 8:51:38 AM (8 days ago) Sep 29

to vim/vim, Push

@MiguelBarro pushed 5 commits.

01951c0 Update breakpoint management.
760dca0 Update debugee terminal set up
be568b2 Update documentation
10be77f Update testing
944ef0a Piggyback fix on gdb's job options. Must be reorder to work properly.

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 1, 2025, 2:14:23 PM (6 days ago) Oct 1

to vim/vim, Push

@MiguelBarro pushed 1 commit.

d1b2c37 Improve program window using socat

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

Copilot

unread,

Oct 1, 2025, 3:48:33 PM (6 days ago) Oct 1

to vim/vim, Subscribed

@Copilot commented on this pull request.

Pull Request Overview

This PR adds remote debugging capabilities to the termdebug plugin, enabling gdb debugging over remote connections like ssh, wsl, and docker. It automatically detects remote contexts and provides path substitution for mapping remote files to local ones.

Key Changes

Added remote terminal window support for launching program windows on remote systems
Implemented path substitution mechanism to map remote file paths to local paths
Added automatic detection for ssh and wsl commands with customizable remote window configuration

Reviewed Changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/testdir/test_plugin_termdebug.vim	Added comprehensive test for remote debugging functionality with path substitution
runtime/doc/terminal.txt	Added documentation for remote debugging features including configuration examples
runtime/doc/tags	Added new documentation tags for remote debugging help references

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

In runtime/doc/terminal.txt:

> +- Use Windows' `UNC` paths to access `WSL2` sources: >
+    let g:termdebug_config['command'] = ['wsl', 'gdb']
+    let g:termdebug_config['substitute_path'] = {
+	\ '/': '\\wsl.localhost\Ubuntu-22.04\',
+	\ '/mnt/c/': 'C:/' }
+< Note: that several mappings are required: one for each drive unit
+  and one for the linux filesystem (queried via `wslpath`).
+
+The plugin "program window" is linked to `gdb` using `pty slave devices`.
+Those must be local to the `gdb` instance, thus remote debugging only works
+on `prompt mode` (see |termdebug_use_prompt|).
+In this mode any `ssh` or `wsl` command would be detected and a similar command
+used to launch a remote `tty` terminal session and connect it to `gdb`.
+
+						*termdebug-remote-window*
+In order to use another remote terminal clients, set "remote_window" entry

Grammar error: 'clients' should be 'client' since it refers to a single client.

⬇️ Suggested change

-In order to use another remote terminal clients, set "remote_window" entry
+In order to use another remote terminal client, set "remote_window" entry

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 1, 2025, 4:00:19 PM (6 days ago) Oct 1

to vim/vim, Subscribed

@MiguelBarro commented on this pull request.

In runtime/doc/terminal.txt:

> +- Use Windows' `UNC` paths to access `WSL2` sources: >
+    let g:termdebug_config['command'] = ['wsl', 'gdb']
+    let g:termdebug_config['substitute_path'] = {
+	\ '/': '\\wsl.localhost\Ubuntu-22.04\',
+	\ '/mnt/c/': 'C:/' }
+< Note: that several mappings are required: one for each drive unit
+  and one for the linux filesystem (queried via `wslpath`).
+
+The plugin "program window" is linked to `gdb` using `pty slave devices`.
+Those must be local to the `gdb` instance, thus remote debugging only works
+on `prompt mode` (see |termdebug_use_prompt|).
+In this mode any `ssh` or `wsl` command would be detected and a similar command
+used to launch a remote `tty` terminal session and connect it to `gdb`.
+
+						*termdebug-remote-window*
+In order to use another remote terminal clients, set "remote_window" entry

If I were referencing a single client, e.g. telnet, no extra option would be required. I would have included extra builtin management (like with ssh or wsl) 🤣.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

Christian Brabandt

unread,

Oct 1, 2025, 4:02:58 PM (6 days ago) Oct 1

to vim/vim, Subscribed

@chrisbra commented on this pull request.

In runtime/doc/terminal.txt:

> @@ -1634,6 +1635,48 @@ interrupt the running program.  But after using the MI command
 "continue" being used for the `:Continue` command, instead of using the
 communication channel.
 
+Remote Debugging ~
+							*termdebug-remote*
+One of the main issues of remote debugging is the access to the debuggee's
+source files. The plugin can profit from system and vim's networking
+capabilities to workaround this.
+						*termdebug-substitute-path*
+Use the `g:termdebug_config['substitute_path']` entry to map remote to local
+files using the same strategy that gdb's `substitute-path` command.

⬇️ Suggested change

-files using the same strategy that gdb's `substitute-path` command.
+files using the same strategy that gdb's `substitute-path` command uses.

In runtime/doc/terminal.txt:

> @@ -1634,6 +1635,48 @@ interrupt the running program.  But after using the MI command
 "continue" being used for the `:Continue` command, instead of using the
 communication channel.
 
+Remote Debugging ~
+							*termdebug-remote*
+One of the main issues of remote debugging is the access to the debuggee's
+source files. The plugin can profit from system and vim's networking
+capabilities to workaround this.
+						*termdebug-substitute-path*
+Use the `g:termdebug_config['substitute_path']` entry to map remote to local
+files using the same strategy that gdb's `substitute-path` command.
+For example:
+- Use |netrw| to access files remoting via ssh: >
+    let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb']
+    let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' }
+< Note: that first is specified the remote machine root path and later

⬇️ Suggested change

-< Note: that first is specified the remote machine root path and later
+< Note: that the key specifies the remote machine root path and the value

In runtime/doc/terminal.txt:

> +						*termdebug-substitute-path*
+Use the `g:termdebug_config['substitute_path']` entry to map remote to local
+files using the same strategy that gdb's `substitute-path` command.
+For example:
+- Use |netrw| to access files remoting via ssh: >
+    let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb']
+    let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' }
+< Note: that first is specified the remote machine root path and later
+  the local one.
+- Use Windows' `UNC` paths to access `WSL2` sources: >
+    let g:termdebug_config['command'] = ['wsl', 'gdb']
+    let g:termdebug_config['substitute_path'] = {
+	\ '/': '\\wsl.localhost\Ubuntu-22.04\',
+	\ '/mnt/c/': 'C:/' }
+< Note: that several mappings are required: one for each drive unit
+  and one for the linux filesystem (queried via `wslpath`).

Do we always need to specify g:termdebug_config['command'] and also g:termdebug_config['substitute_path'] ?

Can you please also give an example. Something along the lines of:

Assuming you want to debug a program on a remote server using ssh, you would need to run the following command: >
ssh user@hostname gdb args /opt/command

This needs to be translated into a command your local Vim can run: >
gdb args scp://user@hostname//opt/command

In runtime/doc/terminal.txt:

> +- Use Windows' `UNC` paths to access `WSL2` sources: >
+    let g:termdebug_config['command'] = ['wsl', 'gdb']
+    let g:termdebug_config['substitute_path'] = {
+	\ '/': '\\wsl.localhost\Ubuntu-22.04\',
+	\ '/mnt/c/': 'C:/' }
+< Note: that several mappings are required: one for each drive unit
+  and one for the linux filesystem (queried via `wslpath`).
+
+The plugin "program window" is linked to `gdb` using `pty slave devices`.
+Those must be local to the `gdb` instance, thus remote debugging only works
+on `prompt mode` (see |termdebug_use_prompt|).
+In this mode any `ssh` or `wsl` command would be detected and a similar command
+used to launch a remote `tty` terminal session and connect it to `gdb`.
+
+						*termdebug-remote-window*
+In order to use another remote terminal clients, set "remote_window" entry

⬇️ Suggested change

-In order to use another remote terminal clients, set "remote_window" entry
+In order to use another remote terminal client, set "remote_window" entry

In runtime/pack/dist/opt/termdebug/plugin/termdebug.vim:

> +  # Check if the user provided a command to launch the program window
+  var term_cmd = null_list
+  if exists('g:termdebug_config') && has_key(g:termdebug_config, 'remote_window')
+    term_cmd = g:termdebug_config['remote_window']
+    term_cmd = type(term_cmd) == v:t_list ? copy(term_cmd) : [term_cmd]
+  else
+    # Check if it is a remote gdb, the program terminal should be started
+    # on the remote machine.
+    const remote_pattern = '^\(ssh\|wsl\)'
+    if gdb_cmd[0] =~? remote_pattern
+      var gdb_pos = indexof(gdb_cmd, $'v:val =~? "^{GetCommand()[-1]}"')
+      if gdb_pos > 0
+        # strip debugger call
+        term_cmd = gdb_cmd[0 : gdb_pos - 1]
+        # create a devoted tty slave device and link to stdin/stdout
+        term_cmd += ['socat', '-d', '-d', '-', 'PTY,raw,echo=0']

that socat is required should be documented or even better checked

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 2, 2025, 5:08:40 PM (5 days ago) Oct 2

to vim/vim, Push

@MiguelBarro pushed 1 commit.

d2deb63 Addressing reviewer's comments

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 2, 2025, 5:12:25 PM (5 days ago) Oct 2

to vim/vim, Subscribed

@MiguelBarro commented on this pull request.

In runtime/pack/dist/opt/termdebug/plugin/termdebug.vim:

> +  # Check if the user provided a command to launch the program window
+  var term_cmd = null_list
+  if exists('g:termdebug_config') && has_key(g:termdebug_config, 'remote_window')
+    term_cmd = g:termdebug_config['remote_window']
+    term_cmd = type(term_cmd) == v:t_list ? copy(term_cmd) : [term_cmd]
+  else
+    # Check if it is a remote gdb, the program terminal should be started
+    # on the remote machine.
+    const remote_pattern = '^\(ssh\|wsl\)'
+    if gdb_cmd[0] =~? remote_pattern
+      var gdb_pos = indexof(gdb_cmd, $'v:val =~? "^{GetCommand()[-1]}"')
+      if gdb_pos > 0
+        # strip debugger call
+        term_cmd = gdb_cmd[0 : gdb_pos - 1]
+        # create a devoted tty slave device and link to stdin/stdout
+        term_cmd += ['socat', '-d', '-d', '-', 'PTY,raw,echo=0']

Let's check. I was afraid it might introduce a roundtrip that could slow down startup, but that doesn't seem to be the case.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 2, 2025, 5:13:32 PM (5 days ago) Oct 2

to vim/vim, Subscribed

@MiguelBarro commented on this pull request.

In runtime/doc/terminal.txt:

> +						*termdebug-substitute-path*
+Use the `g:termdebug_config['substitute_path']` entry to map remote to local
+files using the same strategy that gdb's `substitute-path` command.
+For example:
+- Use |netrw| to access files remoting via ssh: >
+    let g:termdebug_config['command'] = ['ssh', 'hostname', 'gdb']
+    let g:termdebug_config['substitute_path'] = { '/': 'scp://hostname//' }
+< Note: that first is specified the remote machine root path and later
+  the local one.
+- Use Windows' `UNC` paths to access `WSL2` sources: >
+    let g:termdebug_config['command'] = ['wsl', 'gdb']
+    let g:termdebug_config['substitute_path'] = {
+	\ '/': '\\wsl.localhost\Ubuntu-22.04\',
+	\ '/mnt/c/': 'C:/' }
+< Note: that several mappings are required: one for each drive unit
+  and one for the linux filesystem (queried via `wslpath`).

I have reproduced the session example as a remote session.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 6, 2025, 10:32:02 AM (yesterday) Oct 6

to vim/vim, Push

@MiguelBarro pushed 4 commits.

22d00ff Refactor to reuse tty management code
822aad2 Extend remoting to terminal mode
568bd85 Update docs. Remote debugging works on terminal and prompt mode crossplatform.
8b2d986 Extend remoting testing to terminal mode

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 6, 2025, 11:08:51 AM (24 hours ago) Oct 6

to vim/vim, Push

@MiguelBarro pushed 1 commit.

9a0f103 Extend remoting testing to terminal mode

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 6, 2025, 12:19:04 PM (23 hours ago) Oct 6

to vim/vim, Push

@MiguelBarro pushed 3 commits.

4b6dc87 Extend remoting to terminal mode
7d06c44 Update docs. Remote debugging works on:
aec2676 Extend remoting testing to terminal mode

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 6, 2025, 12:28:42 PM (22 hours ago) Oct 6

to vim/vim, Push

@MiguelBarro pushed 1 commit.

73e0bae Extend remoting testing to terminal mode

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 6, 2025, 9:04:26 PM (14 hours ago) Oct 6

to vim/vim, Push

@MiguelBarro pushed 3 commits.

ecb91ba Extend remoting to terminal mode:
3ed12e9 Update docs. Remote debugging works on:
35cc7cc Extend remoting testing to terminal mode

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

MiguelBarro

unread,

Oct 6, 2025, 9:51:51 PM (13 hours ago) Oct 6

to vim/vim, Push

@MiguelBarro pushed 1 commit.

630abb9 Only extend virtual buffer for remoting (socat)

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

Reply all

Reply to author

Forward