3 files changed, 10 insertions, 5 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 08022c3ed6..b4ca88251e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2600,7 +2600,8 @@ vim.filetype.add({filetypes})                             *vim.filetype.add()*
     matched pattern, if any) and should return a string that will be used as
     the buffer's filetype. Optionally, the function can return a second
     function value which, when called, modifies the state of the buffer. This
-    can be used to, for example, set filetype-specific buffer variables.
+    can be used to, for example, set filetype-specific buffer variables. This
+    function will be called by Nvim before setting the buffer's filetype.
 
     Filename patterns can specify an optional priority to resolve cases when a
     file path matches multiple patterns. Higher priorities are matched first.
diff --git a/runtime/filetype.lua b/runtime/filetype.lua
index cf5fe39656..4a4f37a1c4 100644
--- a/runtime/filetype.lua
+++ b/runtime/filetype.lua
@@ -18,12 +18,15 @@ vim.api.nvim_create_autocmd({ 'BufRead', 'BufNewFile', 'StdinReadPost' }, {
         end)
       end
     else
-      vim.api.nvim_buf_call(args.buf, function()
-        vim.api.nvim_cmd({ cmd = 'setf', args = { ft } }, {})
-      end)
+      -- on_detect is called before setting the filetype so that it can set any buffer local
+      -- variables that may be used the filetype's ftplugin
       if on_detect then
         on_detect(args.buf)
       end
+
+      vim.api.nvim_buf_call(args.buf, function()
+        vim.api.nvim_cmd({ cmd = 'setf', args = { ft } }, {})
+      end)
     end
   end,
 })
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index c310eb3e42..a05c1075eb 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -2061,7 +2061,8 @@ end
 --- pattern, if any) and should return a string that will be used as the
 --- buffer's filetype. Optionally, the function can return a second function
 --- value which, when called, modifies the state of the buffer. This can be used
---- to, for example, set filetype-specific buffer variables.
+--- to, for example, set filetype-specific buffer variables. This function will
+--- be called by Nvim before setting the buffer's filetype.
 ---
 --- Filename patterns can specify an optional priority to resolve cases when a
 --- file path matches multiple patterns. Higher priorities are matched first.