refactor: enable filetype detection before user startup scripts (#17040)

3 files changed, 30 insertions, 16 deletions

diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index bb775ec884..7c4b684ca4 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -409,7 +409,17 @@ accordingly, proceeding as follows:
 
 4. Setup |default-mappings| and  |default-autocmds|.
 
-5. Load user config (execute Ex commands from files, environment, …).
+5. Enable filetype and indent plugins.
+	This does the same as the command: >
+		:filetype plugin indent on
+<	which in turn is equivalent to: >
+		:runtime! filetype.lua
+		:runtime! filetype.vim
+		:runtime! ftplugin.vim
+		:runtime! indent.vim
+<	Skipped if the "-u NONE" command line argument was given.
+
+6. Load user config (execute Ex commands from files, environment, …).
 	$VIMINIT environment variable is read as one Ex command line (separate
 	multiple commands with '|' or <NL>).
 					*config* *init.vim* *init.lua* *vimrc* *exrc*
@@ -453,14 +463,6 @@ accordingly, proceeding as follows:
 	-  The file ".nvimrc"
 	-  The file ".exrc"
 
-6. Enable filetype and indent plugins.
-	This does the same as the commands: >
-		:runtime! filetype.vim
-		:runtime! ftplugin.vim
-		:runtime! indent.vim
-<	Skipped if ":filetype … off" was called or if the "-u NONE" command
-	line argument was given.
-
 7. Enable syntax highlighting.
 	This does the same as the command: >
 		:runtime! syntax/syntax.vim
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 4fcaf15717..32a97779e0 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -23,8 +23,12 @@ centralized reference of the differences.
 ==============================================================================
 2. Defaults					            *nvim-defaults*
 
-- Syntax highlighting is enabled by default
-- ":filetype plugin indent on" is enabled by default
+- ":filetype plugin indent on" is enabled by default. This runs before
+  init.vim is sourced so that FileType autocommands in init.vim run after
+  those in filetype.vim.
+- Syntax highlighting is enabled by default. This runs after init.vim is
+  sourced so that users can optionally disable syntax highlighting with
+  ":syntax off".
 
 - 'autoindent' is enabled
 - 'autoread' is enabled
diff --git a/src/nvim/main.c b/src/nvim/main.c
index cbd1f53727..9d1c2ad834 100644
--- a/src/nvim/main.c
+++ b/src/nvim/main.c
@@ -341,9 +341,11 @@ int main(int argc, char **argv)
   init_default_autocmds();
   TIME_MSG("init default autocommands");
 
+  bool vimrc_none = params.use_vimrc != NULL && strequal(params.use_vimrc, "NONE");
+
   // Reset 'loadplugins' for "-u NONE" before "--cmd" arguments.
   // Allows for setting 'loadplugins' there.
-  if (params.use_vimrc != NULL && strequal(params.use_vimrc, "NONE")) {
+  if (vimrc_none) {
     // When using --clean we still want to load plugins
     p_lpl = params.clean;
   }
@@ -351,14 +353,20 @@ int main(int argc, char **argv)
   // Execute --cmd arguments.
   exe_pre_commands(&params);
 
+  if (!vimrc_none) {
+    // Does ":filetype plugin indent on". We do this *before* the user startup scripts to ensure
+    // ftplugins run before FileType autocommands defined in the init file (which allows those
+    // autocommands to overwrite settings from ftplugins).
+    filetype_maybe_enable();
+  }
+
   // Source startup scripts.
   source_startup_scripts(&params);
 
   // If using the runtime (-u is not NONE), enable syntax & filetype plugins.
-  if (params.use_vimrc == NULL || !strequal(params.use_vimrc, "NONE")) {
-    // Does ":filetype plugin indent on".
-    filetype_maybe_enable();
-    // Sources syntax/syntax.vim, which calls `:filetype on`.
+  if (!vimrc_none) {
+    // Sources syntax/syntax.vim. We do this *after* the user startup scripts so that users can
+    // disable syntax highlighting with `:syntax off` if they wish.
     syn_maybe_enable();
   }