From 9202e2c80cea8da009b9c31cf9e0aa204e06397d Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Sat, 27 Jun 2026 13:08:28 -0500
Subject: [PATCH] fix(dir): respect directory buffer lifetime #40453

Problem:
dir.lua leaves previously-navigated directory buffers around.
This is fine by default, but users need a simple way to opt out.

Solution:
1. Respect `set hidden` (via `'bufhidden'`) as one way to make
   previously-navigated dir buffers from showing up.
2. Document a one-liner to hide these buffers
---
 runtime/doc/plugins.txt             |  6 +++++
 runtime/doc/windows.txt             |  2 +-
 runtime/lua/nvim/dir.lua            |  1 -
 test/functional/plugin/dir_spec.lua | 40 +++++++++++++++++++++++++++++
 4 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/runtime/doc/plugins.txt b/runtime/doc/plugins.txt
index 04325b076f..028c7b64e0 100644
--- a/runtime/doc/plugins.txt
+++ b/runtime/doc/plugins.txt
@@ -65,6 +65,12 @@ These keys map to <Plug>(nvim-dir-open), <Plug>(nvim-dir-up), and
 
 The listing is read-only and does not modify the filesystem.
 
+Directory buffers follow the global 'hidden' option by default. To delete them
+after use: >vim
+	autocmd FileType directory setlocal bufhidden=delete
+<
+Use "wipe" to discard all buffer state; see |'bufhidden'|.
+
                                                     *g:loaded_nvim_dir_plugin*
 To disable this plugin, set this in your config before startup: >lua
 	vim.g.loaded_nvim_dir_plugin = 1
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index 3864639121..bac6786de4 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -1429,7 +1429,7 @@ terminal	A terminal window buffer, see |terminal|.  The contents cannot
 directory	Displays directory contents.  Can be used by a file explorer
 		plugin.  The buffer is created with these settings: >
 			:setlocal buftype=nowrite
-			:setlocal bufhidden=delete
+			:setlocal bufhidden=
 			:setlocal noswapfile
 <		The buffer name is the name of the directory and is adjusted
 		when using the |:cd| command.
diff --git a/runtime/lua/nvim/dir.lua b/runtime/lua/nvim/dir.lua
index fc3ca6c73f..3d2eff4d9b 100644
--- a/runtime/lua/nvim/dir.lua
+++ b/runtime/lua/nvim/dir.lua
@@ -85,7 +85,6 @@ local function render(buf, dir)
     not set_buf_options(buf, {
       { 'modeline', false },
       { 'buftype', 'nowrite' },
-      { 'bufhidden', 'hide' },
       { 'buflisted', true },
       { 'swapfile', false },
       { 'readonly', false },
diff --git a/test/functional/plugin/dir_spec.lua b/test/functional/plugin/dir_spec.lua
index 5f15d7d692..40b5855c6d 100644
--- a/test/functional/plugin/dir_spec.lua
+++ b/test/functional/plugin/dir_spec.lua
@@ -215,6 +215,46 @@ describe('nvim.dir', function()
     line_of('beta.txt')
   end)
 
+  it("follows global 'hidden' when abandoned", function()
+    make_fixture()
+    n.clear({ args_rm = { '-u' } })
+
+    command('set hidden')
+
+    edit(root)
+    local root_buf = api.nvim_get_current_buf()
+    eq('', bufopt('bufhidden'))
+
+    edit(subdir)
+    eq(true, api.nvim_buf_is_loaded(root_buf))
+    eq(1, fn.getbufinfo(root_buf)[1].hidden)
+
+    n.clear({ args_rm = { '-u' } })
+    command('set nohidden')
+
+    edit(root)
+    root_buf = api.nvim_get_current_buf()
+    eq('', bufopt('bufhidden'))
+
+    edit(subdir)
+    eq(false, api.nvim_buf_is_loaded(root_buf))
+  end)
+
+  it("preserves custom 'bufhidden' when reloading", function()
+    make_fixture()
+    n.clear({
+      args_rm = { '-u' },
+      args = { '--cmd', [[autocmd FileType directory ++once setlocal bufhidden=delete]] },
+    })
+
+    edit(root)
+    eq('delete', bufopt('bufhidden'))
+
+    feed('R')
+    poke_eventloop()
+    eq('delete', bufopt('bufhidden'))
+  end)
+
   it('reports an error and keeps the buffer when reloading a removed directory', function()
     make_fixture()
     n.clear({ args_rm = { '-u' } })