feat(defaults): jump between :terminal shell prompts with ]]/[[ #32736

runtime/doc/news.txt

@@ -244,6 +244,8 @@ DEFAULTS
     • |[a|, |]a|, |[A|, |]A| navigate through the |argument-list|
     • |[b|, |]b|, |[B|, |]B| navigate through the |buffer-list|
     • |[<Space>|, |]<Space>| add an empty line above and below the cursor
+  • |[[| and |]]| in Normal mode jump between shell prompts for shells which emit
+    OSC 133 sequences ("shell integration" or "semantic prompts").
 
 • Snippet:
   • `<Tab>` in Insert and Select mode maps to `vim.snippet.jump({ direction = 1 })`

runtime/doc/terminal.txt

@@ -185,6 +185,32 @@ clipboard.
 OSC 52 sequences sent from the :terminal buffer do not emit a |TermRequest|
 event. The event is handled directly by Nvim and is not forwarded to plugins.
 
+OSC 133: shell integration			*terminal-osc133*
+
+Some shells will emit semantic escape sequences (OSC 133) to mark the
+beginning and end of a prompt. The start of a prompt is marked with the
+sequence `OSC 133 ; A`. Nvim can be configured to create signs in terminal
+buffers marking shell prompts. Example: >lua
+
+    local ns = vim.api.nvim_create_namespace('terminal_prompt_markers')
+    vim.api.nvim_create_autocmd('TermRequest', {
+      callback = function(args)
+        if string.match(args.data.sequence, '^\027]133;A') then
+          local lnum = args.data.cursor[1]
+          vim.api.nvim_buf_set_extmark(args.buf, ns, lnum - 1, 0, {
+            -- Replace with sign text and highlight group of choice
+            sign_text = '▶',
+            sign_hl_group = 'SpecialChar',
+          })
+        end
+      end,
+    })
+
+    -- Enable signcolumn in terminal buffers
+    vim.api.nvim_create_autocmd('TermOpen', {
+      command = 'setlocal signcolumn=auto',
+    })
+<
 ==============================================================================
 Status Variables				*terminal-status*
 

runtime/doc/vim_diff.txt

@@ -181,7 +181,10 @@ nvim.terminal:
   when 'background' is "light". While this may not reflect the actual
   foreground/background color, it permits 'background' to be retained for a
   nested Nvim instance running in the terminal emulator.
-- TermOpen: Sets default options for |terminal| buffers:
+- TermRequest: Nvim will create extmarks for shells which
+  annotate their prompts with OSC 133 escape sequences, enabling users to
+  quickly navigate between prompts using |[[| and |]]|.
+- TermOpen: Sets default options and mappings for |terminal| buffers:
     - 'nomodifiable'
     - 'undolevels' set to -1
     - 'textwidth' set to 0
@@ -193,6 +196,7 @@ nvim.terminal:
     - 'foldcolumn' set to "0"
     - 'winhighlight' uses |hl-StatusLineTerm| and |hl-StatusLineTermNC| in
       place of |hl-StatusLine| and |hl-StatusLineNC|
+    - |[[| and |]]| to navigate between shell prompts
 
 nvim.cmdwin:
 - CmdwinEnter: Limits syntax sync to maxlines=1 in the |cmdwin|.

runtime/lua/vim/_defaults.lua

@@ -534,14 +534,59 @@ do
     end,
   })
 
+  local nvim_terminal_prompt_ns = vim.api.nvim_create_namespace('nvim.terminal.prompt')
+  vim.api.nvim_create_autocmd('TermRequest', {
+    group = nvim_terminal_augroup,
+    desc = 'Mark shell prompts indicated by OSC 133 sequences for navigation',
+    callback = function(args)
+      if string.match(args.data.sequence, '^\027]133;A') then
+        local lnum = args.data.cursor[1] ---@type integer
+        vim.api.nvim_buf_set_extmark(args.buf, nvim_terminal_prompt_ns, lnum - 1, 0, {})
+      end
+    end,
+  })
+
+  ---@param ns integer
+  ---@param buf integer
+  ---@param count integer
+  local function jump_to_prompt(ns, win, buf, count)
+    local row, col = unpack(vim.api.nvim_win_get_cursor(win))
+    local start = -1
+    local end_ ---@type 0|-1
+    if count > 0 then
+      start = row
+      end_ = -1
+    elseif count < 0 then
+      -- Subtract 2 because row is 1-based, but extmarks are 0-based
+      start = row - 2
+      end_ = 0
+    end
+
+    if start < 0 then
+      return
+    end
+
+    local extmarks = vim.api.nvim_buf_get_extmarks(
+      buf,
+      ns,
+      { start, col },
+      end_,
+      { limit = math.abs(count) }
+    )
+    if #extmarks > 0 then
+      local extmark = extmarks[math.min(#extmarks, math.abs(count))]
+      vim.api.nvim_win_set_cursor(win, { extmark[2] + 1, extmark[3] })
+    end
+  end
+
   vim.api.nvim_create_autocmd('TermOpen', {
     group = nvim_terminal_augroup,
     desc = 'Default settings for :terminal buffers',
-    callback = function()
+    callback = function(args)
-      vim.bo.modifiable = false
+      vim.bo[args.buf].modifiable = false
-      vim.bo.undolevels = -1
+      vim.bo[args.buf].undolevels = -1
-      vim.bo.scrollback = vim.o.scrollback < 0 and 10000 or math.max(1, vim.o.scrollback)
+      vim.bo[args.buf].scrollback = vim.o.scrollback < 0 and 10000 or math.max(1, vim.o.scrollback)
-      vim.bo.textwidth = 0
+      vim.bo[args.buf].textwidth = 0
       vim.wo[0][0].wrap = false
       vim.wo[0][0].list = false
       vim.wo[0][0].number = false
@@ -555,6 +600,13 @@ do
         winhl = winhl .. ','
       end
       vim.wo[0][0].winhighlight = winhl .. 'StatusLine:StatusLineTerm,StatusLineNC:StatusLineTermNC'
+
+      vim.keymap.set('n', '[[', function()
+        jump_to_prompt(nvim_terminal_prompt_ns, 0, args.buf, -vim.v.count1)
+      end, { buffer = args.buf, desc = 'Jump [count] shell prompts backward' })
+      vim.keymap.set('n', ']]', function()
+        jump_to_prompt(nvim_terminal_prompt_ns, 0, args.buf, vim.v.count1)
+      end, { buffer = args.buf, desc = 'Jump [count] shell prompts forward' })
     end,
   })
 

test/functional/api/extmark_spec.lua

@@ -83,7 +83,7 @@ end
 describe('API/extmarks', function()
   local screen
   local marks, positions, init_text, row, col
-  local ns, ns2
+  local ns, ns2 ---@type integer, integer
 
   before_each(function()
     -- Initialize some namespaces and insert 12345 into a buffer
@@ -1425,14 +1425,12 @@ describe('API/extmarks', function()
   end)
 
   it('throws consistent error codes', function()
-    local ns_invalid = ns2 + 1
+    local ns_invalid = ns2 + 1 ---@type integer
-    eq(
+    local err = string.format("Invalid 'ns_id': %d", ns_invalid)
-      "Invalid 'ns_id': 3",
+    eq(err, pcall_err(set_extmark, ns_invalid, marks[1], positions[1][1], positions[1][2]))
-      pcall_err(set_extmark, ns_invalid, marks[1], positions[1][1], positions[1][2])
+    eq(err, pcall_err(api.nvim_buf_del_extmark, 0, ns_invalid, marks[1]))
-    )
+    eq(err, pcall_err(get_extmarks, ns_invalid, positions[1], positions[2]))
-    eq("Invalid 'ns_id': 3", pcall_err(api.nvim_buf_del_extmark, 0, ns_invalid, marks[1]))
+    eq(err, pcall_err(get_extmark_by_id, ns_invalid, marks[1]))
-    eq("Invalid 'ns_id': 3", pcall_err(get_extmarks, ns_invalid, positions[1], positions[2]))
-    eq("Invalid 'ns_id': 3", pcall_err(get_extmark_by_id, ns_invalid, marks[1]))
   end)
 
   it('when col = line-length, set the mark on eol', function()
@@ -1535,7 +1533,7 @@ describe('API/extmarks', function()
         0,
         0,
         {
-          ns_id = 1,
+          ns_id = ns,
           end_col = 0,
           end_row = 1,
           right_gravity = true,
@@ -1595,7 +1593,7 @@ describe('API/extmarks', function()
         hl_group = 'String',
         hl_mode = 'blend',
         line_hl_group = 'Statement',
-        ns_id = 1,
+        ns_id = ns,
         number_hl_group = 'Statement',
         priority = 0,
         right_gravity = false,
@@ -1626,7 +1624,7 @@ describe('API/extmarks', function()
       0,
       0,
       {
-        ns_id = 1,
+        ns_id = ns,
         right_gravity = true,
         priority = 0,
         virt_text = { { '', 'Macro' }, { '', { 'Type', 'Search' } }, { '' } },
@@ -1647,7 +1645,7 @@ describe('API/extmarks', function()
       0,
       0,
       {
-        ns_id = 1,
+        ns_id = ns,
         right_gravity = true,
         ui_watched = true,
         priority = 0,
@@ -1663,7 +1661,7 @@ describe('API/extmarks', function()
       0,
       0,
       {
-        ns_id = 1,
+        ns_id = ns,
         cursorline_hl_group = 'Statement',
         priority = 4096,
         right_gravity = true,
@@ -1683,7 +1681,7 @@ describe('API/extmarks', function()
         end_col = 1,
         end_right_gravity = false,
         end_row = 0,
-        ns_id = 1,
+        ns_id = ns,
         right_gravity = true,
         spell = true,
       },
@@ -1700,7 +1698,7 @@ describe('API/extmarks', function()
         end_col = 1,
         end_right_gravity = false,
         end_row = 0,
-        ns_id = 1,
+        ns_id = ns,
         right_gravity = true,
         spell = false,
       },

test/functional/api/vim_spec.lua

@@ -3167,14 +3167,23 @@ describe('API', function()
 
   describe('nvim_create_namespace', function()
     it('works', function()
-      eq({}, api.nvim_get_namespaces())
+      local orig = api.nvim_get_namespaces()
-      eq(1, api.nvim_create_namespace('ns-1'))
+      local base = vim.iter(orig):fold(0, function(acc, _, v)
-      eq(2, api.nvim_create_namespace('ns-2'))
+        return math.max(acc, v)
-      eq(1, api.nvim_create_namespace('ns-1'))
+      end)
-      eq({ ['ns-1'] = 1, ['ns-2'] = 2 }, api.nvim_get_namespaces())
+      eq(base + 1, api.nvim_create_namespace('ns-1'))
-      eq(3, api.nvim_create_namespace(''))
+      eq(base + 2, api.nvim_create_namespace('ns-2'))
-      eq(4, api.nvim_create_namespace(''))
+      eq(base + 1, api.nvim_create_namespace('ns-1'))
-      eq({ ['ns-1'] = 1, ['ns-2'] = 2 }, api.nvim_get_namespaces())
+
+      local expected = vim.tbl_extend('error', orig, {
+        ['ns-1'] = base + 1,
+        ['ns-2'] = base + 2,
+      })
+
+      eq(expected, api.nvim_get_namespaces())
+      eq(base + 3, api.nvim_create_namespace(''))
+      eq(base + 4, api.nvim_create_namespace(''))
+      eq(expected, api.nvim_get_namespaces())
     end)
   end)
 

test/functional/lua/inspector_spec.lua

@@ -12,7 +12,7 @@ describe('vim.inspect_pos', function()
   end)
 
   it('it returns items', function()
-    local buf, items, other_buf_syntax = exec_lua(function()
+    local buf, ns1, ns2, items, other_buf_syntax = exec_lua(function()
       local buf = vim.api.nvim_create_buf(true, false)
       local buf1 = vim.api.nvim_create_buf(true, false)
       local ns1 = vim.api.nvim_create_namespace('ns1')
@@ -25,7 +25,7 @@ describe('vim.inspect_pos', function()
       vim.api.nvim_buf_set_extmark(buf, ns1, 0, 10, { hl_group = 'Normal' })
       vim.api.nvim_buf_set_extmark(buf, ns2, 0, 10, { hl_group = 'Normal' })
       vim.cmd('syntax on')
-      return buf, vim.inspect_pos(0, 0, 10), vim.inspect_pos(buf1, 0, 10).syntax
+      return buf, ns1, ns2, vim.inspect_pos(0, 0, 10), vim.inspect_pos(buf1, 0, 10).syntax
     end)
 
     eq('', eval('v:errmsg'))
@@ -40,12 +40,12 @@ describe('vim.inspect_pos', function()
           end_row = 0,
           id = 1,
           ns = 'ns1',
-          ns_id = 1,
+          ns_id = ns1,
           opts = {
             hl_eol = false,
             hl_group = 'Normal',
             hl_group_link = 'Normal',
-            ns_id = 1,
+            ns_id = ns1,
             priority = 4096,
             right_gravity = true,
           },
@@ -57,12 +57,12 @@ describe('vim.inspect_pos', function()
           end_row = 0,
           id = 1,
           ns = '',
-          ns_id = 2,
+          ns_id = ns2,
           opts = {
             hl_eol = false,
             hl_group = 'Normal',
             hl_group_link = 'Normal',
-            ns_id = 2,
+            ns_id = ns2,
             priority = 4096,
             right_gravity = true,
           },

test/functional/lua/ui_event_spec.lua

@@ -372,7 +372,7 @@ describe('vim.ui_attach', function()
                                               |
       {3:                                        }|
       {9:Excessive errors in vim.ui_attach() call}|
-      {9:back from ns: 1.}                        |
+      {9:back from ns: 2.}                        |
       {100:Press ENTER or type command to continue}^ |
     ]])
     feed('<cr>')
@@ -419,7 +419,7 @@ describe('vim.ui_attach', function()
                                               |
       {3:                                        }|
       {9:Excessive errors in vim.ui_attach() call}|
-      {9:back from ns: 2.}                        |
+      {9:back from ns: 3.}                        |
       {100:Press ENTER or type command to continue}^ |
     ]])
   end)

test/functional/ui/bufhl_spec.lua

@@ -577,7 +577,7 @@ describe('Buffer highlighting', function()
   end)
 
   describe('virtual text decorations', function()
-    local id1, id2
+    local id1, id2 ---@type integer, integer
     before_each(function()
       insert([[
         1 + 2
@@ -709,7 +709,7 @@ describe('Buffer highlighting', function()
           0,
           0,
           {
-            ns_id = 1,
+            ns_id = id1,
             priority = 0,
             virt_text = s1,
             -- other details
@@ -729,7 +729,7 @@ describe('Buffer highlighting', function()
           lastline,
           0,
           {
-            ns_id = 1,
+            ns_id = id1,
             priority = 0,
             virt_text = s2,
             -- other details
@@ -898,11 +898,15 @@ describe('Buffer highlighting', function()
   end)
 
   it('and virtual text use the same namespace counter', function()
-    eq(1, add_highlight(0, 0, 'String', 0, 0, -1))
+    local base = vim.iter(api.nvim_get_namespaces()):fold(0, function(acc, _, v)
-    eq(2, set_virtual_text(0, 0, 0, { { '= text', 'Comment' } }, {}))
+      return math.max(acc, v)
-    eq(3, api.nvim_create_namespace('my-ns'))
+    end)
-    eq(4, add_highlight(0, 0, 'String', 0, 0, -1))
+
-    eq(5, set_virtual_text(0, 0, 0, { { '= text', 'Comment' } }, {}))
+    eq(base + 1, add_highlight(0, 0, 'String', 0, 0, -1))
-    eq(6, api.nvim_create_namespace('other-ns'))
+    eq(base + 2, set_virtual_text(0, 0, 0, { { '= text', 'Comment' } }, {}))
+    eq(base + 3, api.nvim_create_namespace('my-ns'))
+    eq(base + 4, add_highlight(0, 0, 'String', 0, 0, -1))
+    eq(base + 5, set_virtual_text(0, 0, 0, { { '= text', 'Comment' } }, {}))
+    eq(base + 6, api.nvim_create_namespace('other-ns'))
   end)
 end)

test/functional/ui/decorations_spec.lua

@@ -16,7 +16,7 @@ local assert_alive = n.assert_alive
 local pcall_err = t.pcall_err
 
 describe('decorations providers', function()
-  local screen
+  local screen ---@type test.functional.ui.screen
   before_each(function()
     clear()
     screen = Screen.new(40, 8)
@@ -52,6 +52,7 @@ describe('decorations providers', function()
     posp = getmark(mark, false);
     restore_buffer(&save_buf); ]]
 
+  --- @return integer
   local function setup_provider(code)
     return exec_lua ([[
       local api = vim.api
@@ -848,7 +849,8 @@ for _,item in ipairs(items) do
 end]]
 
 describe('extmark decorations', function()
-  local screen, ns
+  local screen ---@type test.functional.ui.screen
+  local ns ---@type integer
   before_each( function()
     clear()
     screen = Screen.new(50, 15)
@@ -2232,7 +2234,7 @@ describe('extmark decorations', function()
 
     eq({ { 1, 0, 8, { end_col = 13, end_right_gravity = false, end_row = 0,
                        hl_eol = false, hl_group = "NonText", undo_restore = false,
-                       ns_id = 1, priority = 4096, right_gravity = true } } },
+                       ns_id = ns, priority = 4096, right_gravity = true } } },
        api.nvim_buf_get_extmarks(0, ns, {0,0}, {0, -1}, {details=true}))
   end)
 
@@ -2933,7 +2935,8 @@ describe('extmark decorations', function()
 end)
 
 describe('decorations: inline virtual text', function()
-  local screen, ns
+  local screen ---@type test.functional.ui.screen
+  local ns ---@type integer
   before_each( function()
     clear()
     screen = Screen.new(50, 3)
@@ -4675,7 +4678,9 @@ describe('decorations: inline virtual text', function()
 end)
 
 describe('decorations: virtual lines', function()
-  local screen, ns
+  local screen ---@type test.functional.ui.screen
+  local ns ---@type integer
+
   before_each(function()
     clear()
     screen = Screen.new(50, 12)
@@ -5732,7 +5737,9 @@ if (h->n_buckets < new_n_buckets) { // expand
 end)
 
 describe('decorations: signs', function()
-  local screen, ns
+  local screen ---@type test.functional.ui.screen
+  local ns ---@type integer
+
   before_each(function()
     clear()
     screen = Screen.new(50, 10)
@@ -6342,7 +6349,7 @@ l5
 end)
 
 describe('decorations: virt_text', function()
-  local screen
+  local screen ---@type test.functional.ui.screen
 
   before_each(function()
     clear()
@@ -6416,7 +6423,10 @@ describe('decorations: virt_text', function()
 end)
 
 describe('decorations: window scoped', function()
-  local screen, ns, win_other
+  local screen ---@type test.functional.ui.screen
+  local ns ---@type integer
+  local win_other ---@type integer
+
   local url = 'https://example.com'
   before_each(function()
     clear()