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`

lua/nvim-tree.lua

@@ -499,7 +499,7 @@ local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
     highlight_git = false,
     full_name = false,
     highlight_opened_files = "none",
-    root_folder_modifier = ":~",
+    root_folder_label = ":~:s?$?/..?",
     indent_width = 2,
     indent_markers = {
       enable = false,
@@ -679,6 +679,7 @@ local FIELD_OVERRIDE_TYPECHECK = {
   remove_keymaps = { boolean = true, table = true },
   on_attach = { ["function"] = true, string = true },
   sort_by = { ["function"] = true, string = true },
+  root_folder_label = { ["function"] = true, string = true },
 }
 
 local function validate_options(conf)

lua/nvim-tree/legacy.lua

@@ -294,6 +294,9 @@ local function refactored(opts)
   utils.move_missing_val(opts, "", "open_on_tab", opts, "tab.sync", "open", false)
   utils.move_missing_val(opts, "", "open_on_tab", opts, "tab.sync", "close")
   utils.move_missing_val(opts, "", "ignore_buf_on_tab_change", opts, "tab.sync", "ignore")
+
+  -- 2022/11/22
+  utils.move_missing_val(opts, "renderer", "root_folder_modifier", opts, "renderer", "root_folder_label")
 end
 
 local function removed(opts)
@@ -304,8 +307,8 @@ local function removed(opts)
 
   if opts.focus_empty_on_setup then
     notify.warn "focus_empty_on_setup has been removed and will be replaced by a new startup configuration. Please remove this option. See https://bit.ly/3yJch2T"
+    opts.focus_empty_on_setup = nil
   end
-  opts.focus_empty_on_setup = nil
 end
 
 function M.migrate_legacy_options(opts)

lua/nvim-tree/renderer/builder.lua

@@ -8,6 +8,8 @@ local icons = require "nvim-tree.renderer.components.icons"
 local Builder = {}
 Builder.__index = Builder
 
+local DEFAULT_ROOT_FOLDER_LABEL = ":~:s?$?/..?"
+
 function Builder.new(root_cwd)
   return setmetatable({
     index = 0,
@@ -20,8 +22,8 @@ function Builder.new(root_cwd)
   }, Builder)
 end
 
-function Builder:configure_root_modifier(root_folder_modifier)
-  self.root_folder_modifier = root_folder_modifier or ":~"
+function Builder:configure_root_label(root_folder_label)
+  self.root_folder_label = root_folder_label or DEFAULT_ROOT_FOLDER_LABEL
   return self
 end
 
@@ -294,14 +296,21 @@ function Builder:build(tree)
   return self
 end
 
-local function format_root_name(root_cwd, modifier)
-  local base_root = utils.path_remove_trailing(vim.fn.fnamemodify(root_cwd, modifier))
-  return utils.path_join { base_root, ".." }
+local function format_root_name(root_cwd, root_label)
+  if type(root_label) == "function" then
+    local label = root_label(root_cwd)
+    if type(label) == "string" then
+      return label
+    else
+      root_label = DEFAULT_ROOT_FOLDER_LABEL
+    end
+  end
+  return utils.path_remove_trailing(vim.fn.fnamemodify(root_cwd, root_label))
 end
 
 function Builder:build_header(show_header)
   if show_header then
-    local root_name = format_root_name(self.root_cwd, self.root_folder_modifier)
+    local root_name = format_root_name(self.root_cwd, self.root_folder_label)
     self:_insert_line(root_name)
     self:_insert_highlight("NvimTreeRootFolder", 0, string.len(root_name))
     self.index = 1

lua/nvim-tree/renderer/init.lua

@@ -63,7 +63,7 @@ function M.draw()
     lines, hl = help.compute_lines()
   else
     lines, hl, signs = Builder.new(core.get_cwd())
-      :configure_root_modifier(M.config.root_folder_modifier)
+      :configure_root_label(M.config.root_folder_label)
       :configure_trailing_slash(M.config.add_trailing)
       :configure_special_files(M.config.special_files)
       :configure_picture_map(picture_map)