From ef60dd60d66ebc8d15e5f8a97bd691756d211310 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Sun, 23 Jun 2024 21:47:49 +0800 Subject: [PATCH] docs(help): update doc for filetree --- autoload/SpaceVim/layers/core.vim | 126 +++++++++++++++++++++++- doc/SpaceVim.txt | 153 ++++++++++++++++++++++++++---- 2 files changed, 257 insertions(+), 22 deletions(-) diff --git a/autoload/SpaceVim/layers/core.vim b/autoload/SpaceVim/layers/core.vim index 00e8b151f..d3fcd905c 100644 --- a/autoload/SpaceVim/layers/core.vim +++ b/autoload/SpaceVim/layers/core.vim @@ -14,13 +14,13 @@ scriptencoding utf-8 " and it provides filetree, comment key bindings etc. " " @subsection options -" - `filetree_show_hidden`: option for showing hidden file in filetree, +" 1. `filetree_show_hidden`: option for showing hidden file in filetree, " disabled by default. -" - `enable_smooth_scrolling`: enable/disabled smooth scrolling key bindings, +" 2. `enable_smooth_scrolling`: enable/disabled smooth scrolling key bindings, " enabled by default. -" - `enable_filetree_gitstatus`: enable/disable git status column in filetree. -" - `enable_filetree_filetypeicon`: enable/disable filetype icons in filetree. -" - `enable_netrw`: enable/disable netrw, disabled by default. +" 3. `enable_filetree_gitstatus`: enable/disable git status column in filetree. +" 4. `enable_filetree_filetypeicon`: enable/disable filetype icons in filetree. +" 5. `enable_netrw`: enable/disable netrw, disabled by default. " " NOTE: the `enable_vimfiler_gitstatus` and `enable_filetree_gitstatus` option " has been deprecated. Use layer option instead. @@ -34,6 +34,122 @@ if exists('s:string_hi') finish endif +"" +" @section File Tree, usage-file-tree +" @parentsection usage +" The default filetree is `nerdtree`, and the default key binding is ``. +" SpaceVim also provides `SPC f t` and `SPC f T` to open the file tree. +" +" The option @section(options-filemanager) can be used to change file +" manager plugin. For example: +" > +" [options] +" # file manager plugins supported in SpaceVim: +" # - nerdtree (default) +" # - vimfiler: you need to build the vimproc.vim in bundle/vimproc.vim directory +" # - defx: requires +py3 feature +" # - neo-tree: require neovim 0.7.0 +" filemanager = "nerdtree" +" < +" +" VCS integration is also supported, there will be a column status, +" this feature may make filetree slow, so it is not enabled by default. +" To enable this feature, add the layer option `enable_filetree_gitstatus = true` +" to core layer. +" > +" [[layers]] +" name = 'core' +" enable_filetree_gitstatus = true +" < +" +" There is also an option to configure whether open filetree when startup. +" This is enabled by defaul, To disable this feature, you can set the +" @section(options-enable_vimfiler_welcome) to false: +" > +" [options] +" enable_vimfiler_welcome = false +" < +" +" There is also an option to configure the side of the file tree, +" by default it is right. To move the file tree to the left, +" you can use the option: @section(options-filetree_direction). +" > +" [options] +" filetree_direction = "left" +" < +" +" @subsection File tree navigation +" +" Navigation is centered on the `hjkl` keys with the hope of providing +" a fast navigation experience like in vifm(https://github.com/vifm): +" > +" Key Bindings | Descriptions +" --------------------- | ------------------------------------------------- +" | Toggle file explorer +" SPC f t | Toggle file explorer +" SPC f T | Show file explorer +" < +" Key bindings in filetree windows: +" > +" / h | go to parent node and collapse expanded directory +" / j | select next file or directory +" / k | select previous file or directory +" / l | open selected file or expand directory +" | open file or switch to directory +" N | Create new file under cursor +" r | Rename the file under cursor +" d | Delete the file under cursor +" K | Create new directory under cursor +" y y | Copy file full path to system clipboard +" y Y | Copy file to system clipboard +" P | Paste file to the position under the cursor +" . | Toggle hidden files +" s v | Split edit +" s g | Vertical split edit +" p | Preview +" i | Switch to directory history +" v | Quick look +" g x | Execute with vimfiler associated +" ' | Toggle mark current line +" V | Clear all marks +" > | increase filetree screenwidth +" < | decrease filetree screenwidth +" | Jump to first line +" | Jump to last line +" Ctrl-h | Switch to project root directory +" Ctrl-r | Redraw +" < +" +" @subsection Open file with file tree. +" +" If only one file buffer is opened, a file is opened in the active window, +" otherwise we need to use vim-choosewin to select a window to open the file. +" > +" Key Bindings | Descriptions +" --------------- | ---------------------------------------- +" l / | open file in one window +" s g | open file in a vertically split window +" s v | open file in a horizontally split window +" < +" @subsection Override filetree key bindings +" +" If you want to override the default key bindings in filetree windows. +" You can use User autocmd in bootstrap function. for examples: +" > +" function! myspacevim#before() abort +" autocmd User NerdTreeInit +" \ nnoremap :call +" \ g:NERDTreeKeyMap.Invoke('o') +" endfunction +" < +" +" Here is all the autocmd for filetree: +" +" - nerdtree: `User NerdTreeInit` +" - defx: `User DefxInit` +" - vimfiler: `User VimfilerInit` + + let s:enable_smooth_scrolling = 1 let s:enable_netrw = 0 diff --git a/doc/SpaceVim.txt b/doc/SpaceVim.txt index f24b8c9aa..27ce96f0b 100644 --- a/doc/SpaceVim.txt +++ b/doc/SpaceVim.txt @@ -249,16 +249,17 @@ CONTENTS *SpaceVim-contents* 148. xmake........................................ |SpaceVim-layers-xmake| 7. Usage..................................................... |SpaceVim-usage| 1. Error handling......................... |SpaceVim-usage-error-handling| - 2. Toggle UI................................... |SpaceVim-usage-toggle-ui| - 3. alternate file......................... |SpaceVim-usage-alternate-file| - 4. buffers-and-files................... |SpaceVim-usage-buffers-and-files| - 5. command-line-mode................... |SpaceVim-usage-command-line-mode| - 6. custom_plugins......................... |SpaceVim-usage-custom_plugins| - 7. repl............................................. |SpaceVim-usage-repl| - 8. search-and-replace................. |SpaceVim-usage-search-and-replace| - 9. tasks........................................... |SpaceVim-usage-tasks| - 10. undo-tree................................... |SpaceVim-usage-undotree| - 11. windows-and-tabs.................... |SpaceVim-usage-windows-and-tabs| + 2. File Tree................................... |SpaceVim-usage-file-tree| + 3. Toggle UI................................... |SpaceVim-usage-toggle-ui| + 4. alternate file......................... |SpaceVim-usage-alternate-file| + 5. buffers-and-files................... |SpaceVim-usage-buffers-and-files| + 6. command-line-mode................... |SpaceVim-usage-command-line-mode| + 7. custom_plugins......................... |SpaceVim-usage-custom_plugins| + 8. repl............................................. |SpaceVim-usage-repl| + 9. search-and-replace................. |SpaceVim-usage-search-and-replace| + 10. tasks.......................................... |SpaceVim-usage-tasks| + 11. undo-tree................................... |SpaceVim-usage-undotree| + 12. windows-and-tabs.................... |SpaceVim-usage-windows-and-tabs| 8. Plugins................................................. |SpaceVim-plugins| 1. Mapping Guide......................... |SpaceVim-plugins-mapping-guide| 2. Symbol highlighter............... |SpaceVim-plugins-symbol-highlighter| @@ -2043,13 +2044,15 @@ The `core` layer of SpaceVim. This layer is enabled by default, and it provides filetree, comment key bindings etc. OPTIONS -`filetree_show_hidden`: option for showing hidden file in filetree, disabled - by default. -`enable_smooth_scrolling`: enable/disabled smooth scrolling key bindings, - enabled by default. -`enable_filetree_gitstatus`: enable/disable git status column in filetree. -`enable_filetree_filetypeicon`: enable/disable filetype icons in filetree. -`enable_netrw`: enable/disable netrw, disabled by default. + 1. `filetree_show_hidden`: option for showing hidden file in filetree, + disabled by default. + 2. `enable_smooth_scrolling`: enable/disabled smooth scrolling key bindings, + enabled by default. + 3. `enable_filetree_gitstatus`: enable/disable git status column in + filetree. + 4. `enable_filetree_filetypeicon`: enable/disable filetype icons in + filetree. + 5. `enable_netrw`: enable/disable netrw, disabled by default. NOTE: the `enable_vimfiler_gitstatus` and `enable_filetree_gitstatus` option has been deprecated. Use layer option instead. @@ -6187,6 +6190,122 @@ QUICKFIX LIST NAVIGATION q p | jump to previous item in quickfix list < +============================================================================== +FILE TREE *SpaceVim-usage-file-tree* + +The default filetree is `nerdtree`, and the default key binding is ``. +SpaceVim also provides `SPC f t` and `SPC f T` to open the file tree. + +The option |SpaceVim-options-filemanager| can be used to change file manager +plugin. For example: +> + [options] + # file manager plugins supported in SpaceVim: + # - nerdtree (default) + # - vimfiler: you need to build the vimproc.vim in bundle/vimproc.vim + directory + # - defx: requires +py3 feature + # - neo-tree: require neovim 0.7.0 + filemanager = "nerdtree" +< + +VCS integration is also supported, there will be a column status, this feature +may make filetree slow, so it is not enabled by default. To enable this +feature, add the layer option `enable_filetree_gitstatus = true` to core +layer. +> + [[layers]] + name = 'core' + enable_filetree_gitstatus = true +< + +There is also an option to configure whether open filetree when startup. This +is enabled by defaul, To disable this feature, you can set the +|SpaceVim-options-enable_vimfiler_welcome| to false: +> + [options] + enable_vimfiler_welcome = false +< + +There is also an option to configure the side of the file tree, by default it +is right. To move the file tree to the left, you can use the option: +|SpaceVim-options-filetree_direction|. +> + [options] + filetree_direction = "left" +< + +FILE TREE NAVIGATION + +Navigation is centered on the `hjkl` keys with the hope of providing a fast +navigation experience like in vifm(https://github.com/vifm): +> + Key Bindings | Descriptions + --------------------- | ------------------------------------------------- + | Toggle file explorer + SPC f t | Toggle file explorer + SPC f T | Show file explorer +< +Key bindings in filetree windows: +> + / h | go to parent node and collapse expanded directory + / j | select next file or directory + / k | select previous file or directory + / l | open selected file or expand directory + | open file or switch to directory + N | Create new file under cursor + r | Rename the file under cursor + d | Delete the file under cursor + K | Create new directory under cursor + y y | Copy file full path to system clipboard + y Y | Copy file to system clipboard + P | Paste file to the position under the cursor + . | Toggle hidden files + s v | Split edit + s g | Vertical split edit + p | Preview + i | Switch to directory history + v | Quick look + g x | Execute with vimfiler associated + ' | Toggle mark current line + V | Clear all marks + > | increase filetree screenwidth + < | decrease filetree screenwidth + | Jump to first line + | Jump to last line + Ctrl-h | Switch to project root directory + Ctrl-r | Redraw +< + +OPEN FILE WITH FILE TREE. + +If only one file buffer is opened, a file is opened in the active window, +otherwise we need to use vim-choosewin to select a window to open the file. +> + Key Bindings | Descriptions + --------------- | ---------------------------------------- + l / | open file in one window + s g | open file in a vertically split window + s v | open file in a horizontally split window +< +OVERRIDE FILETREE KEY BINDINGS + +If you want to override the default key bindings in filetree windows. You can +use User autocmd in bootstrap function. for examples: +> + function! myspacevim#before() abort + autocmd User NerdTreeInit + \ nnoremap :call + \ g:NERDTreeKeyMap.Invoke('o') + endfunction +< + +Here is all the autocmd for filetree: + +nerdtree: `User NerdTreeInit` +defx: `User DefxInit` +vimfiler: `User VimfilerInit` + ============================================================================== TOGGLE UI *SpaceVim-usage-toggle-ui*