forked from nvim-neo-tree/neo-tree.nvim
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathneo-tree.txt
1907 lines (1572 loc) · 71.6 KB
/
neo-tree.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*neo-tree.txt* Plugin to browse the file system and other tree like structures
CONTENTS *neo-tree*
Introduction ................ |neo-tree-introduction|
Commands .................... |neo-tree-commands|
Mappings .................... |neo-tree-mappings|
Help ...................... |neo-tree-help|
Navigation ................ |neo-tree-navigation|
View Changes .............. |neo-tree-view-changes|
File Actions .............. |neo-tree-file-actions|
Filter .................... |neo-tree-filter|
Custom Mappings ........... |neo-tree-custom-mappings|
Custom Commands ........... |neo-tree-custom-commands|
Configuration ............... |neo-tree-configuration|
Setup ..................... |neo-tree-setup|
Source Selector ........... |neo-tree-source-selector|
Filtered Items ............ |neo-tree-filtered-items|
Preview Mode .............. |neo-tree-preview-mode|
Hijack Netrw Behavior ..... |neo-tree-netrw-hijack|
Component Configs ......... |neo-tree-component-configs|
Git Status ................ |neo-tree-git-status|
Diagnostics ............... |neo-tree-diagnostics|
Indent markers ............ |neo-tree-indent-markers|
Expanders ................. |neo-tree-expanders|
File nesting .............. |neo-tree-file-nesting|
Highlights ................ |neo-tree-highlights|
Events .................... |neo-tree-events|
Components and Renderers .. |neo-tree-renderers|
Buffer Variables .......... |neo-tree-buffer-variables|
Popups .................... |neo-tree-popups|
Other Sources ............... |neo-tree-sources|
Buffers ................... |neo-tree-buffers|
Git Status ................ |neo-tree-git-status-source|
Document Symbols .......... |neo-tree-document-symbols|
INTRODUCTION *neo-tree-introduction*
Neo-tree is a plugin for nvim that can display tree structures in a sidebar,
floating window, or in a split. The current version includes a filesystem
browser, a buffer list, and a git status view.
If you want to use this in splits like |netrw| instead of as a sidebar or
floating window, use the *Split commands, such as |NeoTreeRevealInSplit|. You
may use both styles at the same time if you want.
COMMANDS *:Neotree* *neo-tree-commands*
Neo-tree does not define any default keybindings for nvim. The suggested
keybindings are:
nnoremap / :Neotree toggle current reveal_force_cwd<cr>
nnoremap | :Neotree reveal<cr>
nnoremap gd :Neotree float reveal_file=<cfile> reveal_force_cwd<cr>
nnoremap <leader>b :Neotree toggle show buffers right<cr>
nnoremap <leader>s :Neotree float git_status<cr>
The single |:Neotree| command accepts a range of arguments that give you full
control over the details of what and where it will show. Arguments can be
specified as either a key=value pair or just as the value. The key=value form
is more verbose but may help with clarity. For example, the "buffers" command
above can also be specified as:
>vim
:Neotree action=show source=buffers position=right toggle=true
<
These arguments can be specified in any order. Here is the full list of
arguments you can use:
action~
What to do. Can be one of:
focus : Show and/or switch focus to the specified Neotree window. DEFAULT
show : Show the window, but keep focus on your current window.
close : Close the window(s) specified. Can be combined with "position"
and/or "source" to specify which window(s) to close.
source~
What to show. Can be one of:
filesystem : Show a file browser. DEFAULT
buffers : Show a list of currently open buffers.
git_status : Show the output of `git status` in a tree layout.
position~
Where to show it, can be one of:
left : Open as left hand sidebar. DEFAULT
right : Open as right hand sidebar.
float : Open as floating window.
current : Open within the current window, like netrw or vinegar would.
toggle~
This is a boolean flag. Adding this means that the window will be closed if it
is already open.
dir~
The directory to set as the root/cwd of the specified window. If you include a
directory as one of the arguments, it will be assumed to be this option, you
don't need the full dir=/path. You may use any value that can be passed to the
'expand' function, such as `%:p:h:h` to specify two directories up from the
current file.
git_base~
The base that is used to calculate the git status for each dir/file.
By default it uses `HEAD`, so it shows all changes that are not yet committed.
You can for example work on a feature branch, and set it to `main`. It will
show all changes that happened on the feature branch and main since you
branched off.
Any git ref, commit, tag, or sha will work.
reveal~
This is a boolean flag. Adding this will make Neotree automatically find and
focus the current file when it opens.
reveal_file~
A path to a file to reveal. This supersedes the "reveal" flag so there is no
need to specify both. Use this if you want to reveal something other than the
current file. If you include a path to a file as one of the arguments, it will
be assumed to be this option. Like "dir", you can pass any value that can be
passed to the 'expand' function.
reveal_force_cwd~
This is a boolean flag. Normally, if you use one of the reveal options and the
given file is not within the current working directory, you will be asked if you
want to change the current working directory. If you include this flag, it will
automatically change the directory without prompting. This option implies
"reveal", so you do not need to specify both.
selector~
This is a boolean flag. When you specifically set this to false (`selector=false`)
neo-tree will disable the |neo-tree-source-selector| for that neo-tree
instance. Otherwise, the source selector will depend on what you specified in
the configuration (`config.source_selector.{winbar,statusline}`).
CALLING_FROM_LUA
You can call Neotree commands from your Lua scripts as follows:
>lua
require('neo-tree.command').execute({ ... })
<
For example, you could use the following keymap to make the `-` key reveal the
current file, or if in an unsaved file, the current working directory.
>lua
vim.keymap.set('n', '-', function()
local reveal_file = vim.fn.expand('%:p')
if (reveal_file == '') then
reveal_file = vim.fn.getcwd()
else
local f = io.open(reveal_file, "r")
if (f) then
f.close(f)
else
reveal_file = vim.fn.getcwd()
end
end
require('neo-tree.command').execute({
action = "focus", -- OPTIONAL, this is the default value
source = "filesystem", -- OPTIONAL, this is the default value
position = "left", -- OPTIONAL, this is the default value
reveal_file = reveal_file, -- path to file or folder to reveal
reveal_force_cwd = true, -- change cwd without asking if needed
})
end,
{ desc = "Open neo-tree at current file or working directory" }
);
<
===============================================================================
MAPPINGS ~
===============================================================================
*neo-tree-mappings*
HELP *neo-tree-help*
? = show_help: Shows a popup window with all of the mappings for the current
Neotree window. Pressing one of those keys will close the help
screen and execute the chosen command in the original Neotree
window. NOTE that selecting a line in the help window and
pressing enter will not execute that command, it will just
execute whatever the enter key is mapped to.
NAVIGATION *neo-tree-navigation*
Within the neo-tree window, for the filesystem source, the following mappings
are defined by default. All built-in commands are listed here but some are not
mapped by default. See |neo-tree-custom-commands| for details on how to use them
in a custom mapping.
Note: The "selected" item is the line the cursor is currently on.
< = prev_source: Switches to the previous source.
> = next_source: Switches to the next source.
<bs> = navigate_up: Moves the root directory up one level.
. = set_root: Changes the root directory to the currently
selected folder.
<space> = toggle_node Expand or collapse a node with children, which
may be a directory or a nested file.
<2-LeftMouse> = open: Expand or collapse a folder. If a file is selected,
open it in the window closest to the tree.
<cr> = open: Same as above.
C = close_node: Close node if it is open, else close it's parent.
z = close_all_nodes: Close all nodes in the tree.
close_all_subnodes: Same as "close_node", but also recursively collapse
all subnodes, similar to "close_all_nodes"
expand_all_nodes: Expand all directory nodes in the tree recursively.
P = toggle_preview: Toggles "preview mode", see |neo-tree-preview-mode|
l = focus_preview: Focus the active preview window
<C-f> = scroll_preview: Scrolls preview window down (without focusing it)
see |neo-tree-preview-mode| for params
<C-b> = scroll_preview: Scrolls preview window up (without focusing it)
see |neo-tree-preview-mode| for params
<esc> = revert_preview: Ends "preview_mode" if it is enabled, and reverts
any preview windows to what was being shown before
preview mode began.
S = open_split: Same as open, but opens in a new horizontal split.
s = open_vsplit: Same as open, but opens in a vertical split.
open_rightbelow_vs: Same as open_vsplit, but opens in a right window
of the vertical split.
open_leftabove_vs: Same as open_vsplit, but opens in a left window
of the vertical split.
t = open_tabnew: Same as open, but opens in a new tab.
open_drop: Same as open, but opens with the |:drop| command.
open_tab_drop: Same as open, but opens in a new tab with the
|:drop| command with the |:tab| modifier.
w = open_with_window_picker: Uses the `window-picker` plugin to select a window
to open the selected node in. Requires that
https://github.com/s1n7ax/nvim-window-picker
be installed.
split_with_window_picker: Same as `open_with_window_picker` but opens split
in selected node instead.
vsplit_with_window_picker: Same as `open_with_window_picker` but opens
vertical split in selected node instead.
[g = prev_git_modified: Jump to the previous file reported by `git status`
that is within the current working directory.
This will loop around if you are on the last one.
]g = next_git_modified: Jump to the next file reported by `git status`
that is within the current working directory.
This will loop around if you are on the last one.
FILE ACTIONS *neo-tree-file-actions*
a = add: Create a new file OR directory. Add a `/` to the
end of the name to make a directory. This command
supports an optional `config.show_path` option
which controls what portion of the path is shown
in the prompt. The choices for this option are:
`"none"`: which is the default.
`"relative"`: shows the portion which is relative
to the current root of the tree.
`"absolute"`: is the full path to the current
directory.
The file path also supports BASH style brace
expansion. sequence style ("{00..05..2}") as well
as nested braces. Here are some examples how this
expansion works.
"x{a..e..2}" : "xa", "xc", "xe"
"file.txt{,.bak}" : "file.txt", "file.txt.bak"
"./{a,b}/{00..02}.lua" : "./a/00.lua", "./a/01.lua",
"./a/02.lua", "./b/00.lua",
"./b/01.lua", "./b/02.lua"
A = add_directory: Create a new directory, in this mode it does not
need to end with a `/`. The path also supports
BASH style brace expansion as explained in `add`
command. Also accepts `config.show_path` options
d = delete: Delete the selected file or directory.
Supports visual selection.~
i = show_file_details Show file details in popup window, such as size
and last modified date.
r = rename: Rename the selected file or directory.
b = rename_basename: Rename the selected file or directory without the
extension.
y = copy_to_clipboard: Mark file to be copied.
Supports visual selection.~
x = cut_to_clipboard: Mark file to be cut (moved).
Supports visual selection.~
p = paste_from_clipboard: Copy/move each marked file to the selected folder.
c = copy: Copy the selected file or directory.
Also accepts the optional `config.show_path` option
like the add file action.
m = move: Move the selected file or directory.
Also accepts the optional `config.show_path` option
like the add file action.
VIEW CHANGES *neo-tree-view-changes*
H = toggle_hidden: Toggle whether hidden (filtered items) are shown or not.
R = refresh: Rescan the filesystem and redraw the tree. Changes made
within nvim should be detected automatically, but this is
useful for changes made elsewhere.
o = order_by... Show help menu for order by choices.
oc = ...created: Sort the tree by created date.
od = ...diagnostics: Sort by diagnostic severity.
og = ...git_status: Sort by git status.
om = ...modified: Sort by last modified date.
on = ...name: Sort by name (default sort).
os = ...size: Sort by size.
ot = ...type: Sort by type.
FILTER *neo-tree-filter*
NOTE: All of the below commands are affected by the `find_by_full_path_words`
option:
>lua
require("neo-tree").setup({
filesystem = {
find_by_full_path_words = false,
}
})
<
`false` means it only searches the tail of a path and is the default.
`true` will change the filter into a full path search with space as an implicit
`".*"`, so `fi init` will match: `./sources/filesystem/init.lua`
/ = fuzzy_finder: Filter the tree recursively, searching for
files and folders that contain the specified term as
you type. This will use fd if it is installed, or
find, or which if you are on Windows.
As of v1.28, this acts like a fuzzy finder,
meaning that pressing up/down while the filter
window is open will move the cursor up and down in
the tree, and pressing `<enter>` will open that
item and clear the filter. Any other method of
closing the filter window will also clear the
filter.
D = fuzzy_finder_directory: Like fuzzy_finder above, but only shows directories.
Pressing <enter> on a directory will clear the
search and set the focus on that directory.
Requires `fd` or `find` to be installed~
# = fuzzy_sorter: Sort the tree recursively based on fzy algorithm,
showing top score files. Space separated keywords
are treated as `and` which will be useful to narrow
down as you type. The file list is taken from fd
and other programs mentioned in `fuzzy_finder`.
`fuzzy_sorter_directory` can be used to show list
of directories instead.
f = filter_on_submit: Same as above, but does not search until you hit
enter. Useful if filter_as_you_type is too slow.
Also useful if you want to leave the tree
filtered.
<C-x> = clear_filter: Removes the filter.
PREVIEW MODE *neo-tree-preview-mode*
Preview mode will temporarily show whatever file the cursor is on without
switching focus from the Neo-tree window. By default, files will be previewed
in a new floating window. This can also be configured to automatically choose
an existing split by configuring the command like this:
>lua
require("neo-tree").setup({
window = {
mappings = {
["P"] = { "toggle_preview", config = { use_float = false, use_image_nvim = true } },
["l"] = "focus_preview",
["<C-b>"] = { "scroll_preview", config = {direction = 10} },
["<C-f>"] = { "scroll_preview", config = {direction = -10} },
}
}
})
<
Anything that causes Neo-tree to lose focus will end preview mode. When
`use_float = false`, the window that was taken over by preview mode will revert
back to whatever was shown in that window before preview mode began.
If you want to work with the floating preview mode window in autocmds or other
custom code, the window will have the `neo-tree-preview` filetype.
When preview mode is not using floats, the window will have the window local
variable `neo_tree_preview` set to `1` to indicate that it is being used as a
preview window. You can refer to this in statusline and winbar configs to mark a
window as being used as a preview.
If you have [3rd/image.nvim](https://github.com/3rd/image.nvim) installed, preview
mode supports image rendering by default using kitty graphics protocol or ueberzug.
However, if you do not want this feature, you can disable it by changing the option
`use_image_nvim = false` in the mappings config mentioned above.
CUSTOM MAPPINGS *neo-tree-custom-mappings*
If you want to change the mappings, you can do so in two places. Mappings
defined in `window.mappings` apply to all sources, and mappings defined at the
source level, such as `filesystem.window.mappings` will override and extend
those global mappings for that particular source.
For example:
>lua
require("neo-tree").setup({
window = {
mappings = {
["A"] = "command_a",
["i"] = {
function(state)
local node = state.tree:get_node()
print(node.path)
end,
desc = "print path",
},
}
},
filesystem = {
window = {
mappings = {
["A"] = "command_b"
}
}
}
})
<
The above config will map `A` to command_a for all sources except for
filesystem, which will use command_b instead.
The desc is used to display in the help popup.
If you don't want to use *any* default mappings, you can set
`use_default_mappings = false` in your config.
If you want to remove one or more particular default mappings, you can map
the sequence to `none` or `noop`. For example, if you don’t wish to use
fuzzy finder (default mapping `/`), but instead rely on Neovim’s built-in
search functionality, you can do that like so this:
>lua
require("neo-tree").setup({
filesystem = {
window = {
mappings = {
-- disable fuzzy finder
["/"] = "noop"
}
}
}
})
<
NOTE: Not all commands work for all sources. If it is defined in the source
section in the default config instead of at the root level, that means it is
specific to that source and will not work for others.
CUSTOM MAPPINGS WITH VISUAL MODE *neo-tree-custom-mappings-visual*
If you want to create a mapping that supports visual mode, the way to do that
is to add a second command where the name is the same as the normal mode
command, but with `_visual` added to the end. Any mapping for this command will
then work in either normal or visual mode.
The `_visual` version of the command will be called with a second argument
which is a list of the nodes that were selected when the command was called.
For example, this is how the built-in `delete` command is defined:
>lua
M.delete = function(state, callback)
local tree = state.tree
local node = tree:get_node()
fs_actions.delete_node(node.path, callback)
end
M.delete_visual = function(state, selected_nodes, callback)
local paths_to_delete = {}
for _, node_to_delete in pairs(selected_nodes) do
table.insert(paths_to_delete, node_to_delete.path)
end
fs_actions.delete_nodes(paths_to_delete, callback)
end
<
CUSTOM MAPPINGS WITH ARGUMENTS *neo-tree-custom-mappings-args*
If you want to include options for your mappings, such as `nowait`, you can
set this for all mappings using the `mapping_options` key, or on individual
mappings by specifying them as a table that consists of the command and any
options you want to use. If both are specified, the mapping merges with and
overrides the global `mapping_options`
The command can be either the string name of a built-in command, or a
function, and is specified either as the first element in the table or by
assigning it to the `command` key:
>lua
require("neo-tree").setup({
filesystem = {
window = {
mapping_options = {
noremap = true,
nowait = false,
},
mappings = {
["?"] = {
function(state)
local node = state.tree:get_node()
print(node.name)
end,
desc = "print name",
nowait = true
},
["i"] = {
command = function(state)
local node = state.tree:get_node()
print(node.name)
end,
desc = "print name",
nowait = true,
},
["o"] = {
command = "open",
nowait = true
},
["O"] = {
"open",
nowait = true
},
}
}
}
})
<
See |:map-arguments| for possible values to include. "buffer" and "nnoremap"
are enabled by default.
CUSTOM MAPPINGS WITH CONFIG *neo-tree-custom-mappings-config*
Some mappings may accept an optional `config` table to control it's behavior.
When that is the case, the command is specified using the table syntax, and
the config options are in a table bound to the `config` key:
>lua
require("neo-tree").setup({
filesystem = {
window = {
mappings = {
["a"] = {
"add",
nowait = true
config = {
show_path = "none" -- "none", "relative", "absolute"
}
},
}
}
}
})
<
When the `config` key is used, it is added to the `state` argument that is
passed to the command function:
>lua
M.add = function(state, callback)
local show_path = state.config.show_path
...
<
CUSTOM COMMANDS *neo-tree-custom-commands*
If you want to define your own command, you have two options:
1. You can define (or override) a command in the `commands` section of the
config for each source, then reference that by name in a mapping.
2. You can map directly to a function and skip defining a command.
You probably want #2:
>lua
require("neo-tree").setup({
filesystem = {
window = {
mappings = {
["?"] = function(state)
local node = state.tree:get_node()
print(node.name)
end
}
}
}
})
<
..or
>lua
local print_me = function(state)
local node = state.tree:get_node()
print(node.name)
end
require("neo-tree").setup({
filesystem = {
window = {
mappings = {
["?"] = print_me
}
}
}
})
<
...but if you want #1, here is how that works:
>lua
require("neo-tree").setup({
filesystem = {
commands = {
print_me = function(state)
local node = state.tree:get_node()
print(node.name)
end
},
mappings = {
["?"] = "print_me"
}
}
})
<
GLOBAL CUSTOM COMMANDS *neo-tree-custom-commands-global*
You can also have global custom commands that will be added to all available
sources. If you need it you can then override it in a specific source.
>lua
require("neo-tree").setup({
commands = {
hello = function() -- define a global "hello world" function
print("Hello world")
end
},
window = {
mappings = {
["<C-c>"] = "hello"
-- define a global mapping to call 'hello' in every source
}
},
filesystem = {
commands = {
-- override implementation of the 'hello' action in filesystem source
hello = function()
print("Hello inside filesystem")
end
}
}
})
<
Now when pressing `<C-c>` in 'buffers' or 'git_status' it will print "Hello world",
but in 'filesystem' it will print "Hello inside filesystem".
================================================================================
CONFIGURATION ~
================================================================================
*neo-tree-configuration*
Neo-tree is highly configurable and you should be able to make it do whatever
you want without having to change the internal code. Here are the ways you can
customize it:
By setting config options in the |neo-tree-setup| function. This is for very
common items and is how you would configure most lua plugins. You can also
change the look by configuring the appropriate highlight groups, see
|neo-tree-highlights|.
By creating custom mappings (see |neo-tree-mappings|). You can of course just
change what keys are mapped to which built-in functions, but you can also map
keys to a custom function and do whatever you want. See the wiki for some
examples: https://github.com/nvim-neo-tree/neo-tree.nvim/wiki/Recipes#commands
By hooking into |neo-tree-events|. You can do things like always clear the
search after opening a file, or define a custom file opener to choose what
window will be used, or respond to file events like renames and moves.
By configuring, rearranging, adding, or removing |neo-tree-renderers| for each
node type. The renderer is a list of components, such as "icon" and "name",
which determines how each node displayed. Use them as lego pieces to build what
you want to see.
By adding or replacing |neo-tree-components|. Components are the functions
called by the renderers, and they return the text and highlight group to be
displayed. If you want to gather extra data just once per render to be used by a
custom component, you can do so in the "before_render" event (see
|neo-tree-events|), set that data on the `state` object, and reference it in the
component. See the wiki for some examples of custom components:
https://github.com/nvim-neo-tree/neo-tree.nvim/wiki/Recipes#components
SETUP *neo-tree-setup*
To override the defaults or add new functionality, call the setup() function
with your overrides. For example, to add your own mappings in 'lua':
>lua
require("neo-tree").setup({
filesystem = {
window = {
mappings = {
["<F5>"] = "refresh",
["o"] = "open",
}
}
}
})
<
NOTE: The mappings you define will be merged with the default mappings. If you
wish to remove a default mapping without overriding it with your own function,
assign it the the string "none". This will cause it to be skipped and allow any
existing global mappings to work.
NOTE: SOME OPTIONS ARE ONLY DOCUMENTED IN THE DEFAULT CONFIG!~
Run `:lua require("neo-tree").paste_default_config()` to dump the fully
commented default config in your current file. Even if you don't want to use
that config as your starting point, you still may want to dump it to a blank
lua file just to read it as documentation.
SOURCE SELECTOR *neo-tree-source-selector*
You can enable a clickable source selector in either the winbar
(requires neovim 0.8+) or the statusline. To do so, set one of these options
to `true`:
>lua
requires("neo-tree").setup({
source_selector = {
winbar = false,
statusline = false
}
})
<
The configuration options for source selector are all placed inside
`source_selector` table. Below are the options with their default values and
type notations.
>lua
requires("neo-tree").setup({
source_selector = {
winbar = false, -- toggle to show selector on winbar
statusline = false, -- toggle to show selector on statusline
show_scrolled_off_parent_node = false, -- boolean
sources = { -- table
{
source = "filesystem", -- string
display_name = " Files " -- string | nil
},
{
source = "buffers", -- string
display_name = " Buffers " -- string | nil
},
{
source = "git_status", -- string
display_name = " Git " -- string | nil
},
},
content_layout = "start", -- string
tabs_layout = "equal", -- string
truncation_character = "…", -- string
tabs_min_width = nil, -- int | nil
tabs_max_width = nil, -- int | nil
padding = 0, -- int | { left: int, right: int }
separator = { left = "▏", right= "▕" }, -- string | { left: string, right: string, override: string | nil }
separator_active = nil, -- string | { left: string, right: string, override: string | nil } | nil
show_separator_on_edge = false, -- boolean
highlight_tab = "NeoTreeTabInactive", -- string
highlight_tab_active = "NeoTreeTabActive", -- string
highlight_background = "NeoTreeTabInactive", -- string
highlight_separator = "NeoTreeTabSeparatorInactive", -- string
highlight_separator_active = "NeoTreeTabSeparatorActive", -- string
},
})
<
Keywords: >
<tab> <tab> <tab> <background>
┃/ a \/ b \/ c \ ┃ <- edge of window
^ ^^ ^^ ^ separators
left separator right separator
<
Configuration Options:
When `show_scrolled_off_parent_node` is `true`, tabs are replaced with the parent
path of the top visible node when scrolled down.
`sources` is a table to configure the contents of the bar. Previously known
as `tab_labels`. Sources should be a table of tables. Each table inside
`sources` must contain a `source` key, which will refer to the "name" of the
source to add to the bar. A second optional `display_name` key can be
provided to modify how you wish that source to appear in the bar. It is
safe to add sources that do not exist, they will simply be omitted from
the bar if they cannot be found.
NOTE: If `source_selector` is enabled (via `winbar=true` or `statusline=true`)
then the `default_source` will be updated to be the first entry of
`sources`.
`content_layout` defines how the labels are placed inside a tab. This only takes
effect when the tab width is greater than the length of label i.e.
`tabs_layout = "equal", "focus"` or when `tabs_min_width` is large enough.
Following options are available.
'start' : left aligned / bufname \/..
'end' : right aligned / bufname \/...
'center' : centered with equal padding / bufname \/...
`tabs_layout` defines how the tabs are aligned inside the window when there is
more than enough space. The following options are available. `active` will
expand the focused tab as much as possible. Bars denote the edge of window.
'start' : left aligned ┃/ ~ \/ ~ \/ ~ \ ┃
'end' : right aligned ┃ / ~ \/ ~ \/ ~ \┃
'center' : centered with equal padding ┃ / ~ \/ ~ \/ ~ \ ┃
'equal' : expand all tabs equally to fit the window width ┃/ ~ \/ ~ \/ ~ \┃
'active' : expand the focused tab to fit the window width ┃/ focused tab \/ ~ \/ ~ \┃
`padding` defines the global padding of the source selector. It can be an
integer or a table with keys `left` and `right`. Setting `padding = 2` is
exactly the same as `{ left = 2, right = 2 }`
`separator` and `separator_active` take string or table to define the separators
surrounding non-active and active tab respectively. When `separator_active` is
`nil`, it falls back to `separator`. They require three keys `left`, `right`,
and `override` which define how the separators of neighboring tabs are merged
together. The following four options are available for `override`. The examples
show the result of `{ left = "/", right = "\", override = ... }`
'nil' : never merged / ~ \/ ~ \/ ~ \...
'"right"' : all merged to the right / ~ \ ~ \ ~ \...
'"left"' : all merged to the left / ~ / ~ / ~ /...
'"active"' : merged towards the active tab / ~ / focused tab \ ~ \...
When set to string such as "┃", it is equivalent to
`{ left = "┃", right = "┃", override = "active" }`.
`show_separator_on_edge` takes a boolean value where `false` (default) hides the
separators on the far left / right. Especially useful when left and right
separator are the same.
'true' : ┃/ ~ \/ ~ \/ ~ \┃
'false' : ┃ ~ \/ ~ \/ ~ ┃
CURRENT WORKING DIRECTORY *neo-tree-cwd*
By default, Neo-tree will maintain a two-way binding between the cwd of nvim and
the root of the tree. Changing the root in Neo-tree will change the working
directory of nvim and vice versa.
In the case of a sidebar, this will be synced with the tab working directory
(|tcd|). If you open it in the "current" position, aka netrw style, it will sync
with the window local working directory (|lcd|).
These defaults can be changed by setting the following options:
>lua
require("neo-tree").setup({
filesystem = {
bind_to_cwd = true, -- true creates a 2-way binding between vim's cwd and neo-tree's root
cwd_target = {
sidebar = "tab", -- sidebar is when position = left or right
current = "window" -- current is when position = current
},
}
})
<
In addition to `"tab"` and `"window"`, you can also set the target to `"global"`
for either option, which is the same as using the |cd| command. Setting the target
to `"none"` will prevent neo-tree from setting vim's cwd for that position.
FILTERED ITEMS *neo-tree-filtered-items*
The `filesystem` source has a `filtered_items` section in it's config that
allows you to specify what files and folders should be hidden. By default, any
item identified by these filters will not be visible, but that visibility can
be toggled on and off with a command. Each type of filter has a corresponding
highlight group which will be applied when they are visible, see
|neo-tree-highlights| for details. The following options are available:
>lua
require("neo-tree").setup({
filesystem = {
filtered_items = {
visible = false, -- when true, they will just be displayed differently than normal items
hide_dotfiles = true,
hide_gitignored = true,
hide_hidden = true, -- only works on Windows for hidden files/directories
hide_by_name = {
".DS_Store",
"thumbs.db",
--"node_modules",
},
hide_by_pattern = {
--"*.meta",
--"*/src/*/tsconfig.json",
},
always_show = { -- remains visible even if other settings would normally hide it
--".gitignored",
},
always_show_by_pattern = { -- uses glob style patterns
--".env*",
},
never_show = { -- remains hidden even if visible is toggled to true, this overrides always_show
--".DS_Store",
--"thumbs.db",
},
never_show_by_pattern = { -- uses glob style patterns
--".null-ls_*",
},
},
}
})
<
The `visible` option just defines the default value. This value is toggled by
the "toggle_hidden" command, which is mapped to H by default.
The `hide_dotfiles` option just hides anything that starts with `. `(period).
The `hide_gitignored` option will query git for the files and folders being
shown, and hide those that are marked as ignored.
The `hide_hidden` option only will work on Windows using the Windows logic
that determines if a file or directory is hidden.
The `hide_by_name` option is a list of file/folder names that should be
hidden. This is an exact match.
The `hide_by_pattern` option uses glob syntax, which is converted to lua
patterns. No guarantees on how it handles advanced patterns.
The `always_show` option is a list of file/folder names that will always be
visible, even if other settings would normally hide it. This section takes
precedence over all other options except for `never_show`.
the `always_show_by_pattern` option is a list of file/folder patterns that
always will be visible. This section takes precedence over all other options
except `never_show`.
The `never_show` option is the same as `hide_by_name`, except that those items
will remain hidden even if you toggle `visible` to true. This section takes
precedence over the others.
The `never_show_by_pattern` option is the same as `hide_by_pattern`, except that
those items will remain hidden even if you toggle `visible` to true. This
section takes precedence over the others.
NETRW HIJACK BEHAVIOR *neo-tree-netrw-hijack*
Neo-tree can and does hijack Netrw by default. This is configurable and can be
disabled if you use Netrw, or have other plugins that use Netrw functionality.
This can be controlled by setting the `filesystem.hijack_netrw_behavior` option
to one of: