feat(renderer): add renderer.root_folder_label (#1746)

* Add new renderer setting `add_root_updir` to fix #1743.

* Fix default value in docs.

* Remove proposed “add_root_updir” and rename “root_folder_modifier” to “root_folder_label”. Also, “root_folder_label” can be also a function now.

* chore: warn users about breaking change

* fix(#1743): use silent migration of root_folder_modifier

* fix(#1743): add example, document previous renderer.root_folder_modifier

* Add check to validate return type of “root_folder_label” is string.

* Change “root_folder_label” default value to “:~:s?$?/..?”.

* Add missing keyword “local” to local variable “label”.

Co-authored-by: David Aguilera <david.aguilera@neliosoftware.com>
Co-authored-by: gegoune <dev@clog.rocks>
Co-authored-by: Alexander Courtis <alex@courtis.org>

doc/nvim-tree-lua.txt

@@ -221,7 +221,7 @@ Subsequent calls to setup will replace the previous configuration.
         highlight_git = false,
         full_name = false,
         highlight_opened_files = "none",
-        root_folder_modifier = ":~",
+        root_folder_label = ":~:s?$?/..?",
         indent_width = 2,
         indent_markers = {
           enable = false,
@@ -760,11 +760,17 @@ UI rendering setup
     Value can be `"none"`, `"icon"`, `"name"` or `"all"`.
       Type: `string`, Default: `"none"`
 
-    *nvim-tree.renderer.root_folder_modifier*
+    *nvim-tree.renderer.root_folder_label*  (previously `renderer.root_folder_modifier`)
     In what format to show root folder. See `:help filename-modifiers` for
-    available options.
-      Type: `string`, Default: `":~"`
+    available `string` options.
+      Type: `string` or `function(root_cwd)`, Default: `":~:s?$?/..?"`
 
+      Function is passed the absolute path of the root folder and should return a string.
+      e.g. >
+        my_root_folder_label = function(path)
+          return ".../" .. vim.fn.fnamemodify(path, ":t")
+        end
+<
     *nvim-tree.renderer.indent_width*
     Number of spaces for an each tree nesting level. Minimum 1.
       Type: `number`, Default: `2`