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,31 +571,39 @@ 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*
-Changes how files within the same directory are sorted.
-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"`
+*nvim-tree.sort*
+File and folder sorting options.
 
-  Function may perform a sort or return a string with one of the above
-  methods. It is passed a table of nodes to be sorted, each node containing:
-  - `absolute_path`: `string`
-  - `executable`:    `boolean`
-  - `extension`:     `string`
-  - `filetype`:      `string`
-  - `link_to`:       `string`
-  - `name`:          `string`
-  - `type`:          `"directory"` | `"file"` | `"link"`
+    *nvim-tree.sort.sorter*  (previously `sort_by`)
+    Changes how files within the same directory are sorted.
+    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"`
 
-  Example: sort by name length: >
-    local sort_by = function(nodes)
-      table.sort(nodes, function(a, b)
-        return #a.name < #b.name
-      end)
-    end
+      Function may perform a sort or return a string with one of the above
+      methods. It is passed a table of nodes to be sorted, each node containing:
+      - `absolute_path`: `string`
+      - `executable`:    `boolean`
+      - `extension`:     `string`
+      - `filetype`:      `string`
+      - `link_to`:       `string`
+      - `name`:          `string`
+      - `type`:          `"directory"` | `"file"` | `"link"`
+
+      Example: sort by name length: >
+        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`