From c29f75ce42af4f808bfbdce21b865bd76f3bf4ef Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Mon, 16 Mar 2026 18:30:08 -0400
Subject: [PATCH] docs: add paste-file-from-clipboard recipe (#156) (#153)

docs: add paste-file-from-clipboard recipe (stevearc/oil.nvim#156)

Problem: users on macOS want to copy a file in Finder and paste it
into an oil directory. The parser rejects absolute paths, but a
recipe-level solution avoids touching the mutation pipeline entirely.

Solution: add `oil-recipe-paste-file-from-clipboard` recipe that reads
the system clipboard, resolves it as a file path, and copies it into
the current oil directory via `vim.uv.fs_copyfile`.
---
 doc/oil.txt     | 33 +++++++++++++++++++++++++++++++++
 doc/upstream.md |  2 +-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/doc/oil.txt b/doc/oil.txt
index 2397207..999e1a8 100644
--- a/doc/oil.txt
+++ b/doc/oil.txt
@@ -1288,6 +1288,39 @@ the buffer renders.
     })
 <
 
+                                          *oil-recipe-paste-file-from-clipboard*
+
+Copy a file into the current oil directory by pasting its absolute path from
+the system clipboard. Useful on macOS where copying a file in Finder places its
+path in the clipboard.
+>lua
+    vim.keymap.set("n", "gp", function()
+      local oil = require("oil")
+      local dir = oil.get_current_dir()
+      if not dir then
+        return
+      end
+      local path = vim.fn.getreg("+"):gsub("\n$", "")
+      if path == "" or not vim.uv.fs_stat(path) then
+        vim.notify("Clipboard does not contain a valid file path", vim.log.levels.WARN)
+        return
+      end
+      local name = vim.fn.fnamemodify(path, ":t")
+      local dest = dir .. name
+      vim.uv.fs_copyfile(path, dest, function(err)
+        vim.schedule(function()
+          if err then
+            vim.notify("Copy failed: " .. err, vim.log.levels.ERROR)
+          else
+            local bufname = vim.api.nvim_buf_get_name(0)
+            require("oil.view").set_last_cursor(bufname, name)
+            require("oil.actions").refresh.callback()
+          end
+        end)
+      end)
+    end, { desc = "Paste file from clipboard path into oil directory" })
+<
+
 --------------------------------------------------------------------------------
 EVENTS                                                                *oil-events*
 
diff --git a/doc/upstream.md b/doc/upstream.md
index 24e7dc5..8c0cd47 100644
--- a/doc/upstream.md
+++ b/doc/upstream.md
@@ -37,7 +37,7 @@ issues against this fork.
 | [#85](https://github.com/stevearc/oil.nvim/issues/85)   | Git status column                                          | consolidated into [#121](https://github.com/barrettruth/canola.nvim/issues/121)                                                                                                           |
 | [#95](https://github.com/stevearc/oil.nvim/issues/95)   | Undo after renaming files                                  | open                                                                                                                                                                                      |
 | [#117](https://github.com/stevearc/oil.nvim/issues/117) | Move file into new dir via slash in name                   | consolidated into [#32](https://github.com/barrettruth/canola.nvim/issues/32)                                                                                                             |
-| [#156](https://github.com/stevearc/oil.nvim/issues/156) | Paste path of files into oil buffer                        | open                                                                                                                                                                                      |
+| [#156](https://github.com/stevearc/oil.nvim/issues/156) | Paste path of files into oil buffer                        | fixed — added `oil-recipe-paste-file-from-clipboard`                                                                                                                                      |
 | [#200](https://github.com/stevearc/oil.nvim/issues/200) | Highlights not working when opening a file                 | not actionable — cannot reproduce, nvim 0.9.4                                                                                                                                             |
 | [#207](https://github.com/stevearc/oil.nvim/issues/207) | Suppress "no longer available" message                     | fixed — `cleanup_buffers_on_delete` option                                                                                                                                                |
 | [#210](https://github.com/stevearc/oil.nvim/issues/210) | FTP support                                                | open                                                                                                                                                                                      |