docs: clarify get_current_dir nil return and add telescope recipe

Problem: get_current_dir returns nil in several cases that were not
documented, causing confusion when used in keymaps that open pickers
like Telescope (#682). Also, posix_to_os_path could crash on Windows
when no drive letter is found.

Solution: expand get_current_dir docs to explain nil return cases, add
a Telescope recipe with nil guards, and add a defensive nil check in
posix_to_os_path.

Cherry-picked from: stevearc/oil.nvim#727

doc/oil.txt

@@ -301,7 +301,36 @@ toggle_hidden()                                                *oil.toggle_hidde
 
 
 get_current_dir({bufnr}): nil|string                         *oil.get_current_dir*
-    Get the current directory
+    Get the current directory for the given oil buffer. Returns the directory
+    path as a string, or nil in the following cases:
+    - The buffer is not an oil buffer
+    - The buffer uses a non-files adapter (ssh, s3, trash)
+    - The current buffer changed (e.g. after opening a Telescope picker)
+
+    When calling this function inside a keymap that also opens another
+    plugin's window (e.g. Telescope), capture the directory BEFORE the
+    call that changes the buffer context:
+>lua
+        ["<leader>ff"] = {
+            function()
+                local dir = require("oil").get_current_dir()
+                if dir then
+                    require("telescope.builtin").find_files({ cwd = dir })
+                end
+            end,
+            mode = "n",
+            nowait = true,
+            desc = "Find files in the current directory"
+        },
+<
+
+    You can also pass a specific buffer number to avoid depending on the
+    current buffer:
+>lua
+        local bufnr = vim.api.nvim_get_current_buf()
+        -- ... operations that may change the current buffer ...
+        local dir = require("oil").get_current_dir(bufnr)
+<
 
     Parameters:
       {bufnr} `nil|integer`
@@ -519,9 +548,10 @@ The `keymaps` option in `oil.setup` allow you to create mappings using all the s
         -- a table with the mapping as the first element.
         ["<leader>ff"] = {
             function()
-                require("telescope.builtin").find_files({
+                local dir = require("oil").get_current_dir()
-                    cwd = require("oil").get_current_dir()
+                if dir then
-                })
+                    require("telescope.builtin").find_files({ cwd = dir })
+                end
             end,
             mode = "n",
             nowait = true,

doc/recipes.md

@@ -7,6 +7,7 @@ Have a cool recipe to share? Open a pull request and add it to this doc!
 - [Toggle file detail view](#toggle-file-detail-view)
 - [Show CWD in the winbar](#show-cwd-in-the-winbar)
 - [Hide gitignored files and show git tracked hidden files](#hide-gitignored-files-and-show-git-tracked-hidden-files)
+- [Open Telescope file finder in the current oil directory](#open-telescope-file-finder-in-the-current-oil-directory)
 
 <!-- /TOC -->
 
@@ -125,3 +126,44 @@ require("oil").setup({
   },
 })
 ```
+
+## Open Telescope file finder in the current oil directory
+
+When using `get_current_dir()` in a keymap that also opens another plugin's UI (like Telescope), always capture the directory in a local variable **before** the call that changes the buffer context. Passing `get_current_dir()` directly as an argument works because Lua evaluates arguments before calling the function, but any subsequent calls will see the new buffer.
+
+```lua
+require("oil").setup({
+  keymaps = {
+    ["<leader>ff"] = {
+      desc = "Find files in the current directory",
+      callback = function()
+        local dir = require("oil").get_current_dir()
+        if not dir then
+          vim.notify("Could not get oil directory", vim.log.levels.WARN)
+          return
+        end
+        require("telescope.builtin").find_files({ cwd = dir })
+      end,
+    },
+    ["<leader>fg"] = {
+      desc = "Live grep in the current directory",
+      callback = function()
+        local dir = require("oil").get_current_dir()
+        if not dir then
+          vim.notify("Could not get oil directory", vim.log.levels.WARN)
+          return
+        end
+        require("telescope.builtin").live_grep({ cwd = dir })
+      end,
+    },
+  },
+})
+```
+
+If you need the directory after an operation that might change the current buffer, pass the buffer number explicitly:
+
+```lua
+local bufnr = vim.api.nvim_get_current_buf()
+-- ... some operation that changes the current buffer ...
+local dir = require("oil").get_current_dir(bufnr)
+```

lua/oil/fs.lua

@@ -87,6 +87,9 @@ M.posix_to_os_path = function(path)
   if M.is_windows then
     if vim.startswith(path, "/") then
       local drive = path:match("^/(%a+)")
+      if not drive then
+        return path
+      end
       local rem = path:sub(drive:len() + 2)
       return string.format("%s:%s", drive, rem:gsub("/", "\\"))
     else