feat(ALL)!: unify naming of buffers created by modules

Details:
- Having descriptive names makes helper buffers more identifiable in
  `:buffers!` output (instead of many `[Scratch]` entries) and allows
  storing useful information about buffer (like file path of explorer
  buffers in 'mini.files') closer to it.

Resolve #1455

Author: echasnovski

CHANGELOG.md

@@ -6,6 +6,8 @@
     - BREAKING: Use single space padding for default title/footer.
     - BREAKING: Use 'single' as default window border in modules where it can be configured. On Neovim>=0.11 also respect non-empty 'winborder' option with lower precedence than explicitly configured value for the module.
 
+- BREAKING FEATURE: Unify how module-related buffers are named: `mini<module-name>://<buffer-number>/<useful-info>`. This structure allows creating identifiable, reasonably unique, and useful buffer names. This is a user facing change because in some cases the shown buffer's name will change (like in statusline of opened 'mini.starter' buffer or output of `:buffers!`).
+
 ## mini.ai
 
 - FEATURE: textobject identifier can now be any single character supported by `:h getcharstr()`. This also makes it possible to use characters outside of Latin alphanumeric and punctuation sets as `custom_textobjects` keys. Default textobject is extended to be anything but Latin letters (to fall back to `:h text-objects`).

README.md

@@ -163,6 +163,8 @@ These modules don't quite fit in any of the previous categories.
 
 - **Buffer local configuration**. Each module can be additionally configured to use certain runtime config settings locally to buffer. See `mini.nvim-buffer-local-config` section in help file for more information.
 
+- **Buffer names**. All module-related buffers are named according to the following format: `mini<module-name>://<buffer-number>/<useful-info>` (forward slashes are used on any platform; `<useful-info>` may be empty). This structure allows creating identifiable, reasonably unique, and useful buffer names. For example, 'mini.files' buffers are created per displayed directory/file with names like `minifiles://10/path/to/displayed/directory`.
+
 - **Disabling**. Each module's core functionality can be disabled globally or locally to buffer. See "Disabling" section in module's help page for more details. See `mini.nvim-disabling-recipes` section in main help file for common recipes.
 
 - **Silencing**. Each module providing non-error feedback can be configured to not do that by setting `config.silent = true` (either inside `setup()` call or on the fly).

doc/mini.txt

@@ -100,6 +100,13 @@ Table of contents:
   to use certain runtime config settings locally to buffer.
   See |mini.nvim-buffer-local-config| for more information.
 
+- <Buffer names>. All module-related buffers are named according to the
+  following format: `mini<module-name>://<buffer-number>/<useful-info>`
+  (forward slashes are used on any platform; `<useful-info>` may be empty).
+  This structure allows creating identifiable, reasonably unique, and useful
+  buffer names. For example, |MiniFiles| buffers are created per displayed
+  directory/file with names like `minifiles://10/path/to/displayed/directory`.
+
 - <Disabling>. Each module's core functionality can be disabled globally or
   locally to buffer. See "Disabling" section in module's help page for more
   details. See |mini.nvim-disabling-recipes| for common recipes.

lua/mini/animate.lua

@@ -1809,6 +1809,7 @@ H.make_openclose_step = function(action_type, win_id, config)
       -- Empty buffer should always be valid (might have been closed by user command)
       if H.empty_buf_id == nil or not vim.api.nvim_buf_is_valid(H.empty_buf_id) then
         H.empty_buf_id = vim.api.nvim_create_buf(false, true)
+        H.set_buf_name(H.empty_buf_id, 'open-close-scratch')
       end
 
       -- Set step config to window. Possibly (re)open (it could have been
@@ -2099,6 +2100,8 @@ H.check_type = function(name, val, ref, allow_nil)
   H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
 end
 
+H.set_buf_name = function(buf_id, name) vim.api.nvim_buf_set_name(buf_id, 'minianimate://' .. buf_id .. '/' .. name) end
+
 H.validate_if = function(predicate, x, x_name)
   local is_valid, msg = predicate(x, x_name)
   if not is_valid then H.error(msg) end

lua/mini/bufremove.lua

@@ -161,7 +161,8 @@ MiniBufremove.unshow_in_window = function(win_id)
     local has_previous = pcall(vim.cmd, 'bprevious')
     if has_previous and cur_buf ~= vim.api.nvim_win_get_buf(win_id) then return end
 
-    -- Create new listed buffer
+    -- Create new listed scratch buffer
+    -- NOTE: leave it unnamed to allow `:h buffer-reuse`
     local new_buf = vim.api.nvim_create_buf(true, false)
     vim.api.nvim_win_set_buf(win_id, new_buf)
   end)

lua/mini/clue.lua

@@ -1639,7 +1639,10 @@ end
 -- Buffer ---------------------------------------------------------------------
 H.buffer_update = function()
   local buf_id = H.state.buf_id
-  if not H.is_valid_buf(buf_id) then buf_id = vim.api.nvim_create_buf(false, true) end
+  if not H.is_valid_buf(buf_id) then
+    buf_id = vim.api.nvim_create_buf(false, true)
+    H.set_buf_name(buf_id, 'content')
+  end
 
   -- Compute content data
   local keys = H.query_to_keys(H.state.query)
@@ -1887,6 +1890,8 @@ H.check_type = function(name, val, ref, allow_nil)
   H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
 end
 
+H.set_buf_name = function(buf_id, name) vim.api.nvim_buf_set_name(buf_id, 'miniclue://' .. buf_id .. '/' .. name) end
+
 H.map = function(mode, lhs, rhs, opts)
   if lhs == '' then return end
   opts = vim.tbl_deep_extend('force', { silent = true }, opts or {})

lua/mini/colors.lua

@@ -822,6 +822,7 @@ MiniColors.interactive = function(opts)
   local init_cs = opts.colorscheme == nil and MiniColors.get_colorscheme()
     or MiniColors.as_colorscheme(opts.colorscheme)
   local buf_id = vim.api.nvim_create_buf(true, true)
+  H.set_buf_name(buf_id, 'interactive')
 
   -- Write header lines
   local header_lines = {
@@ -2360,6 +2361,8 @@ H.check_type = function(name, val, ref, allow_nil)
   H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
 end
 
+H.set_buf_name = function(buf_id, name) vim.api.nvim_buf_set_name(buf_id, 'minicolors://' .. buf_id .. '/' .. name) end
+
 H.round = function(x)
   if x == nil then return nil end
   return math.floor(x + 0.5)

lua/mini/completion.lua

@@ -1209,7 +1209,7 @@ H.show_info_window = function()
   if lines == nil or H.is_whitespace(lines) then return end
 
   -- Ensure permanent buffer with "markdown" highlighting to display info
-  H.ensure_buffer(H.info, 'MiniCompletion:completion-item-info')
+  H.ensure_buffer(H.info, 'item-info')
   H.ensure_highlight(H.info, 'markdown')
   vim.api.nvim_buf_set_lines(H.info.bufnr, 0, -1, false, lines)
 
@@ -1366,7 +1366,7 @@ H.show_signature_window = function()
   end
 
   -- Ensure permanent buffer with current highlighting to display signature
-  H.ensure_buffer(H.signature, 'MiniCompletion:signature-help')
+  H.ensure_buffer(H.signature, 'signature-help')
   H.ensure_highlight(H.signature, vim.bo.filetype)
   vim.api.nvim_buf_set_lines(H.signature.bufnr, 0, -1, false, lines)
 
@@ -1516,7 +1516,7 @@ H.ensure_buffer = function(cache, name)
 
   local buf_id = vim.api.nvim_create_buf(false, true)
   cache.bufnr = buf_id
-  vim.api.nvim_buf_set_name(buf_id, name)
+  H.set_buf_name(buf_id, name)
   vim.bo[buf_id].buftype = 'nofile'
 end
 
@@ -1592,6 +1592,8 @@ H.check_type = function(name, val, ref, allow_nil)
   H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
 end
 
+H.set_buf_name = function(buf_id, name) vim.api.nvim_buf_set_name(buf_id, 'minicompletion://' .. buf_id .. '/' .. name) end
+
 H.is_valid_buf = function(buf_id) return type(buf_id) == 'number' and vim.api.nvim_buf_is_valid(buf_id) end
 
 H.is_valid_win = function(win_id) return type(win_id) == 'number' and vim.api.nvim_win_is_valid(win_id) end

lua/mini/deps.lua

@@ -780,9 +780,6 @@ H.cache = {
   git_version = nil,
 }
 
--- Buffer name counts
-H.buf_name_counts = {}
-
 -- Helper functionality =======================================================
 -- Settings -------------------------------------------------------------------
 H.setup_config = function(config)
@@ -1254,7 +1251,7 @@ H.clean_confirm = function(paths)
     if #paths_to_delete == 0 then return H.notify('Nothing to delete') end
     H.clean_delete(paths_to_delete)
   end
-  H.show_confirm_buf(lines, { name = 'mini-deps://confirm-clean', exec_on_write = finish_clean })
+  H.show_confirm_buf(lines, { name = 'confirm-clean', exec_on_write = finish_clean })
 
   -- Define basic highlighting
   vim.cmd('syntax region MiniDepsHint start="^\\%1l" end="\\%' .. n_header .. 'l$"')
@@ -1377,7 +1374,7 @@ H.update_feedback_confirm = function(lines)
     MiniDeps.update(names, { force = true, offline = true })
   end
 
-  H.show_confirm_buf(report, { name = 'mini-deps://confirm-update', exec_on_write = finish_update, setup_folds = true })
+  H.show_confirm_buf(report, { name = 'confirm-update', exec_on_write = finish_update, setup_folds = true })
 
   -- Define basic highlighting
   vim.cmd('syntax region MiniDepsHint start="^\\%1l" end="\\%' .. n_header .. 'l$"')
@@ -1414,7 +1411,7 @@ end
 H.show_confirm_buf = function(lines, opts)
   -- Show buffer
   local buf_id = vim.api.nvim_create_buf(true, true)
-  H.buf_set_name(buf_id, opts.name)
+  H.set_buf_name(buf_id, opts.name)
   vim.api.nvim_buf_set_lines(buf_id, 0, -1, false, lines)
   vim.cmd('tab sbuffer ' .. buf_id)
   local tab_num, win_id = vim.api.nvim_tabpage_get_number(0), vim.api.nvim_get_current_win()
@@ -1590,6 +1587,8 @@ H.check_type = function(name, val, ref, allow_nil)
   H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
 end
 
+H.set_buf_name = function(buf_id, name) vim.api.nvim_buf_set_name(buf_id, 'minideps://' .. buf_id .. '/' .. name) end
+
 H.notify = vim.schedule_wrap(function(msg, level)
   level = level or 'INFO'
   if H.get_config().silent and level ~= 'ERROR' and level ~= 'WARN' then return end
@@ -1626,13 +1625,6 @@ H.source = function(path)
   pcall(function() vim.cmd('source ' .. vim.fn.fnameescape(path)) end)
 end
 
-H.buf_set_name = function(buf_id, name)
-  local n = (H.buf_name_counts[name] or 0) + 1
-  H.buf_name_counts[name] = n
-  local suffix = n == 1 and '' or ('_' .. n)
-  vim.api.nvim_buf_set_name(buf_id, name .. suffix)
-end
-
 -- TODO: Remove after compatibility with Neovim=0.9 is dropped
 H.islist = vim.fn.has('nvim-0.10') == 1 and vim.islist or vim.tbl_islist
 

lua/mini/extra.lua

@@ -590,6 +590,7 @@ MiniExtra.pickers.git_branches = function(local_opts, opts)
     local win_target = (pick.get_picker_state().windows or {}).target
     if win_target == nil or not H.is_valid_win(win_target) then return end
     local buf_id = vim.api.nvim_create_buf(true, true)
+    H.set_buf_name(buf_id, item:match('^%*?%s*(%S+)'))
     preview(buf_id, item)
     vim.api.nvim_win_set_buf(win_target, buf_id)
   end
@@ -645,6 +646,7 @@ MiniExtra.pickers.git_commits = function(local_opts, opts)
     local win_target = (pick.get_picker_state().windows or {}).target
     if win_target == nil or not H.is_valid_win(win_target) then return end
     local buf_id = vim.api.nvim_create_buf(true, true)
+    H.set_buf_name(buf_id, item:match('^(%S+)'))
     preview(buf_id, item)
     -- Set filetype on opened buffer to trigger appropriate `FileType` event
     vim.bo[buf_id].filetype = 'git'
@@ -2076,6 +2078,8 @@ H.check_type = function(name, val, ref, allow_nil)
   H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
 end
 
+H.set_buf_name = function(buf_id, name) vim.api.nvim_buf_set_name(buf_id, 'miniextra://' .. buf_id .. '/' .. name) end
+
 H.is_valid_win = function(win_id) return type(win_id) == 'number' and vim.api.nvim_win_is_valid(win_id) end
 
 H.ensure_text_width = function(text, width)