docs(upstream): triage stevearc/oil.nvim#280 and consolidate #325 (#166)

* docs(upstream): consolidate stevearc/oil.nvim#325 into #164

Problem: upstream #325 (spurious "could not find parent window" warning
on startup) was still marked open in the tracker.

Solution: created canola.nvim#164 to track the `WinNew`/`BufEnter`
race condition and updated the tracker status.

* docs(upstream): triage stevearc/oil.nvim#280 as not actionable

Problem: upstream #280 (vim-projectionist support) was still marked
open. `BufNewFile` does not fire for oil-created files because the
file already exists on disk by the time it is opened.

Solution: the `OilFileCreated` user event is the correct hook point.
Added an `oil-recipe-file-templates` recipe documenting both a simple
template approach and a precise vim-projectionist shim via
`OilFileCreated`. Updated the tracker status.

* docs(upstream): close PR #721 as not actionable

`OilFileCreated` already covers the use case addressed by the
`create_hook` draft PR.

doc/oil.txt

@@ -1321,6 +1321,50 @@ path in the clipboard.
     end, { desc = "Paste file from clipboard path into oil directory" })
 <
 
+                                              *oil-recipe-file-templates*
+
+Apply initial content to newly created files using the |OilFileCreated| event.
+This is the recommended alternative to relying on |BufNewFile|, which does not
+fire for files created through oil (the file already exists on disk by the
+time it is opened). >lua
+    vim.api.nvim_create_autocmd("User", {
+      pattern = "OilFileCreated",
+      callback = function(args)
+        local path = args.data.path
+        local ext = vim.fn.fnamemodify(path, ":e")
+        local templates = {
+          sh = { "#!/usr/bin/env bash", "" },
+          py = { "#!/usr/bin/env python3", "" },
+        }
+        if templates[ext] then
+          vim.fn.writefile(templates[ext], path)
+        end
+      end,
+    })
+<
+
+For integration with vim-projectionist or any plugin that hooks |BufNewFile|,
+use |OilFileCreated| to track oil-created files, then fire |BufNewFile| the
+first time each file is opened. This is more precise than checking for empty
+buffers on |BufRead|: >lua
+    local oil_created = {}
+    vim.api.nvim_create_autocmd("User", {
+      pattern = "OilFileCreated",
+      callback = function(args)
+        oil_created[args.data.path] = true
+      end,
+    })
+    vim.api.nvim_create_autocmd("BufRead", {
+      callback = function(args)
+        local path = vim.api.nvim_buf_get_name(args.buf)
+        if oil_created[path] then
+          oil_created[path] = nil
+          vim.api.nvim_exec_autocmds("BufNewFile", { buffer = args.buf })
+        end
+      end,
+    })
+<
+
 --------------------------------------------------------------------------------
 EVENTS                                                                *oil-events*
 

doc/upstream.md

@@ -27,7 +27,7 @@ issues against this fork.
 | [#591](https://github.com/stevearc/oil.nvim/pull/591) | release-please changelog                          | not applicable                                                                       |
 | [#667](https://github.com/stevearc/oil.nvim/pull/667) | Virtual text columns + headers                    | consolidated into [#142](https://github.com/barrettruth/canola.nvim/issues/142)      |
 | [#708](https://github.com/stevearc/oil.nvim/pull/708) | Move file into new dir by renaming                | consolidated into [#32](https://github.com/barrettruth/canola.nvim/issues/32)        |
-| [#721](https://github.com/stevearc/oil.nvim/pull/721) | `create_hook` to populate file contents           | deferred — fixing via autocmd event                                                  |
+| [#721](https://github.com/stevearc/oil.nvim/pull/721) | `create_hook` to populate file contents           | not actionable — `OilFileCreated` event already covers the use case (see [#280](https://github.com/stevearc/oil.nvim/issues/280)) |
 | [#728](https://github.com/stevearc/oil.nvim/pull/728) | `open_split` for opening oil in a split           | deferred — tracked as [#2](https://github.com/barrettruth/canola.nvim/issues/2)      |
 
 ## Issues
@@ -47,7 +47,7 @@ issues against this fork.
 | [#254](https://github.com/stevearc/oil.nvim/issues/254) | Buffer modified highlight group                            | tracked in [#129](https://github.com/barrettruth/canola.nvim/issues/129)                                                                                                                  |
 | [#263](https://github.com/stevearc/oil.nvim/issues/263) | Diff mode                                                  | open                                                                                                                                                                                      |
 | [#276](https://github.com/stevearc/oil.nvim/issues/276) | Archives manipulation                                      | not actionable — nvim has builtin zip support                                                                                                                                             |
-| [#280](https://github.com/stevearc/oil.nvim/issues/280) | vim-projectionist support                                  | open                                                                                                                                                                                      |
+| [#280](https://github.com/stevearc/oil.nvim/issues/280) | vim-projectionist support                                  | not actionable — `OilFileCreated` event provides the correct hook; recipe added to docs                                                                                                   |
 | [#288](https://github.com/stevearc/oil.nvim/issues/288) | Oil failing to load                                        | not actionable — no reliable repro, likely lazy.nvim timing                                                                                                                               |
 | [#289](https://github.com/stevearc/oil.nvim/issues/289) | Show absolute path toggle                                  | not actionable — display solved by `get_win_title`, editing consolidated into [#32](https://github.com/barrettruth/canola.nvim/issues/32)                                                 |
 | [#294](https://github.com/stevearc/oil.nvim/issues/294) | Can't handle emojis in filenames                           | not actionable — libuv bug ([nodejs/node#49042](https://github.com/nodejs/node/issues/49042))                                                                                             |