feat(#2313): sort_by -> sort.sorter, add sort.folders_first default true (#2314)

* feat(#2313): add sort_folders_first, default true

* feat(#2313): add sort.sorter, sort.folders_firs

doc/nvim-tree-lua.txt

@@ -95,7 +95,9 @@ Setup the plugin in your `init.lua` >
 
   -- OR setup with some options
   require("nvim-tree").setup({
-    sort_by = "case_sensitive",
+    sort = {
+      sorter = "case_sensitive",
+    },
     view = {
       width = 30,
     },
@@ -312,7 +314,10 @@ applying configuration.
       hijack_cursor = false,
       hijack_netrw = true,
       hijack_unnamed_buffer_when_opening = false,
-      sort_by = "name",
+      sort = {
+        sorter = "name",
+        folders_first = true,
+      },
       root_dirs = {},
       prefer_startup_root = false,
       sync_root_with_cwd = false,
@@ -566,12 +571,15 @@ Hijack netrw windows (overridden if |disable_netrw| is `true`)
 Reloads the explorer every time a buffer is written to.
   Type: `boolean`, Default: `true`
 
-*nvim-tree.sort_by*
+*nvim-tree.sort*
-Changes how files within the same directory are sorted.
+File and folder sorting options.
-Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`,
+
-`"suffix"`, `"filetype"` or a function.
+    *nvim-tree.sort.sorter*  (previously `sort_by`)
-`"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz`
+    Changes how files within the same directory are sorted.
-`"suffix"` uses the last e.g. `.gz`
+    Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`,
+    `"suffix"`, `"filetype"` or a function.
+    `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz`
+    `"suffix"` uses the last e.g. `.gz`
       Type: `string` | `function(nodes)`, Default: `"name"`
 
       Function may perform a sort or return a string with one of the above
@@ -585,12 +593,17 @@ Can be one of `"name"`, `"case_sensitive"`, `"modification_time"`, `"extension"`
       - `type`:          `"directory"` | `"file"` | `"link"`
 
       Example: sort by name length: >
-    local sort_by = function(nodes)
+        local sorter = function(nodes)
           table.sort(nodes, function(a, b)
             return #a.name < #b.name
           end)
         end
 <
+    *nvim-tree.sort.sort_folders_first*
+    Sort folders before files. Has no effect when |nvim-tree.sort.sorter| is a
+    function.
+      Type: `boolean`, Default: `true`
+
 *nvim-tree.hijack_unnamed_buffer_when_opening*
 Opens in place of the unnamed buffer if it's empty.
   Type: `boolean`, Default: `false`

lua/nvim-tree.lua

@@ -366,7 +366,10 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
   hijack_cursor = false,
   hijack_netrw = true,
   hijack_unnamed_buffer_when_opening = false,
-  sort_by = "name",
+  sort = {
+    sorter = "name",
+    folders_first = true,
+  },
   root_dirs = {},
   prefer_startup_root = false,
   sync_root_with_cwd = false,
@@ -613,7 +616,7 @@ local FIELD_OVERRIDE_TYPECHECK = {
   min = { string = true, ["function"] = true, number = true },
   remove_keymaps = { boolean = true, table = true },
   on_attach = { ["function"] = true, string = true },
-  sort_by = { ["function"] = true, string = true },
+  sorter = { ["function"] = true, string = true },
   root_folder_label = { ["function"] = true, string = true, boolean = true },
   picker = { ["function"] = true, string = true },
 }

lua/nvim-tree/explorer/sorters.lua

@@ -3,10 +3,10 @@ local M = {}
 local C = {}
 
 --- Predefined comparator, defaulting to name
---- @param sort_by string as per options
+--- @param sorter string as per options
 --- @return function
-local function get_comparator(sort_by)
+local function get_comparator(sorter)
-  return C[sort_by] or C.name
+  return C[sorter] or C.name
 end
 
 ---Create a shallow copy of a portion of a list.
@@ -68,7 +68,7 @@ local function split_merge(t, first, last, comparator)
   merge(t, first, mid, last, comparator)
 end
 
----Perform a merge sort using sort_by option.
+---Perform a merge sort using sorter option.
 ---@param t table nodes
 function M.sort(t)
   if C.user then
@@ -115,7 +115,7 @@ function M.sort(t)
 
     split_merge(t, 1, #t, mini_comparator) -- sort by user order
   else
-    split_merge(t, 1, #t, get_comparator(M.config.sort_by))
+    split_merge(t, 1, #t, get_comparator(M.config.sort.sorter))
   end
 end
 
@@ -123,11 +123,14 @@ local function node_comparator_name_ignorecase_or_not(a, b, ignorecase)
   if not (a and b) then
     return true
   end
+
+  if M.config.sort.folders_first then
     if a.nodes and not b.nodes then
       return true
     elseif not a.nodes and b.nodes then
       return false
     end
+  end
 
   if ignorecase then
     return a.name:lower() <= b.name:lower()
@@ -148,11 +151,14 @@ function C.modification_time(a, b)
   if not (a and b) then
     return true
   end
+
+  if M.config.sort.folders_first then
     if a.nodes and not b.nodes then
       return true
     elseif not a.nodes and b.nodes then
       return false
     end
+  end
 
   local last_modified_a = 0
   local last_modified_b = 0
@@ -174,6 +180,7 @@ function C.suffix(a, b)
   end
 
   -- directories go first
+  if M.config.sort.folders_first then
     if a.nodes and not b.nodes then
       return true
     elseif not a.nodes and b.nodes then
@@ -181,6 +188,7 @@ function C.suffix(a, b)
     elseif a.nodes and b.nodes then
       return C.name(a, b)
     end
+  end
 
   -- dotfiles go second
   if a.name:sub(1, 1) == "." and b.name:sub(1, 1) ~= "." then
@@ -223,11 +231,13 @@ function C.extension(a, b)
     return true
   end
 
+  if M.config.sort.folders_first then
     if a.nodes and not b.nodes then
       return true
     elseif not a.nodes and b.nodes then
       return false
     end
+  end
 
   if a.extension and not b.extension then
     return true
@@ -249,11 +259,13 @@ function C.filetype(a, b)
   local b_ft = vim.filetype.match { filename = b.name }
 
   -- directories first
+  if M.config.sort.folders_first then
     if a.nodes and not b.nodes then
       return true
     elseif not a.nodes and b.nodes then
       return false
     end
+  end
 
   -- one is nil, the other wins
   if a_ft and not b_ft then
@@ -272,10 +284,10 @@ end
 
 function M.setup(opts)
   M.config = {}
-  M.config.sort_by = opts.sort_by
+  M.config.sort = opts.sort
 
-  if type(opts.sort_by) == "function" then
+  if type(M.config.sort.sorter) == "function" then
-    C.user = opts.sort_by
+    C.user = M.config.sort.sorter
   end
 end
 

lua/nvim-tree/legacy.lua

@@ -41,6 +41,9 @@ local function refactored(opts)
     end
     opts.view.adaptive_size = nil
   end
+
+  -- 2023/07/15
+  utils.move_missing_val(opts, "", "sort_by", opts, "sort", "sorter", true)
 end
 
 local function deprecated(opts)