Repository navigation
Expand file tree
/
Copy pathmini-files.txt
More file actions
978 lines (752 loc) · 37.5 KB
/
Copy pathmini-files.txt
File metadata and controls
978 lines (752 loc) · 37.5 KB
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
*mini.files* Navigate and manipulate file system
*MiniFiles*
MIT License Copyright (c) 2023 Evgeni Chasnovski
==============================================================================
Features:
- Navigate file system using column view (Miller columns) to display nested
directories. See |MiniFiles-navigation| for overview.
- Opt-in preview of file or directory under cursor.
- Manipulate files and directories by editing text buffers: create, delete,
copy, rename, move. See |MiniFiles-manipulation| for overview.
- Use as default file explorer instead of |netrw|.
- Configurable:
- Filter/prefix/sort of file system entries.
- Mappings used for common explorer actions.
- UI options: whether to show preview of file/directory under cursor, etc.
- Bookmarks for quicker navigation.
What it doesn't do:
- Try to be replacement of system file explorer. It is mostly designed to
be used within Neovim to quickly explore file system structure, open
files, and perform some quick file system edits.
- Work on remote locations. Only local file system is supported.
- Provide built-in interactive toggle of content `filter` and `sort`.
See |MiniFiles-examples| for some common examples.
- Provide out of the box extra information like git or diagnostic status.
This can be achieved by setting |extmarks| on appropriate event(s)
(see |MiniFiles-events|)
Notes:
- This module is written and thoroughly tested on Linux. Support for other
platform/OS (like Windows or MacOS) is a goal, but there is no guarantee.
- Works on all supported versions but using Neovim>=0.9 is recommended.
- This module silently reacts to not enough permissions:
- In case of missing file, check its or its parent read permissions.
- In case of no manipulation result, check write permissions.
# Dependencies ~
Suggested dependencies (provide extra functionality, will work without them):
- Enabled |MiniIcons| module to show icons near file/directory names.
Falls back to 'nvim-tree/nvim-web-devicons' plugin or uses default icons.
# Setup ~
This module needs a setup with `require('mini.files').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniFiles`
which you can use for scripting or manually (with `:lua MiniFiles.*`).
See |MiniFiles.config| for available config settings.
You can override runtime config settings (like mappings or window options)
locally to buffer inside `vim.b.minifiles_config` which should have same
structure as `MiniFiles.config`. See |mini.nvim-buffer-local-config| for
more details.
# Comparisons ~
- 'nvim-tree/nvim-tree.lua':
- Provides tree view of file system, while this module uses column view.
- File system manipulation is done with custom set of mappings for each
action, while this module is designed to do that by editing text.
- Has more out of the box functionality with extra configuration, while
this module has not (by design).
- 'stevearc/oil.nvim':
- Uses single window to show information only about currently explored
directory, while this module uses column view to show whole currently
explored branch.
- Also uses text editing to manipulate file system entries.
- Can work for remote file systems, while this module can not (by design).
- 'nvim-neo-tree/neo-tree.nvim':
- Compares to this module mostly the same as 'nvim-tree/nvim-tree.lua'.
# Highlight groups ~
* `MiniFilesBorder` - border of regular windows.
* `MiniFilesBorderModified` - border of windows showing modified buffer.
* `MiniFilesCursorLine` - cursor line in explorer windows.
* `MiniFilesDirectory` - text and icon representing directory.
* `MiniFilesFile` - text representing file.
* `MiniFilesNormal` - basic foreground/background highlighting.
* `MiniFilesTitle` - title of regular windows.
* `MiniFilesTitleFocused` - title of focused window.
To change any highlight group, modify it directly with |:highlight|.
# Disabling ~
This plugin provides only manually started functionality, so no disabling
is available.
------------------------------------------------------------------------------
*MiniFiles-navigation*
Navigation ~
Every navigation starts by calling |MiniFiles.open()|, either directly or via
mapping (see its help for examples of some common scenarios). It will show
an explorer consisting of side-by-side floating windows with the following
principles:
- Explorer shows one branch of nested directories at a time.
- Explorer consists from several windows:
- Each window displays entries of a single directory in a modifiable
scratch buffer.
- Windows are organized left to right: for any particular window the left
neighbor is its parent directory and right neighbor - its child.
- Explorer windows are the viewport to some part of current branch, meaning
that their opening/closing does not affect the branch. This matters, for
example, if there are more elements in the branch than can be shown windows.
- Every buffer line represents separate file system entry following certain
format (not visible for users by default; set |conceallevel| to 0 to see it)
- Once directory is shown, its buffer is not updated automatically following
external file system changes. Manually use |MiniFiles.synchronize()| for that.
After opening explorer, in-buffer navigation is done the same way as any
regular buffer, except without some keys reserved for built-in actions.
Most common ways to navigate are:
- Press `j` to move cursor onto next (lower) entry in current directory.
- Press `k` to move cursor onto previous (higher) entry in current directory.
- Press `l` to expand entry under cursor (see "Go in" action).
- Press `h` to focus on parent directory (see "Go out" action).
Cursor positions in each directory buffer are tracked and saved during
navigation. This allows for more convenient repeated navigation to some
previously visited branch.
Available built-in actions (see "Details" for more information): >
| Action | Keys | Description |
|-------------|------|------------------------------------------------|
| Close | q | Close explorer |
|-------------|------|------------------------------------------------|
| Go in | l | Expand entry (show directory or open file) |
|-------------|------|------------------------------------------------|
| Go in plus | L | Expand entry plus extra action |
|-------------|------|------------------------------------------------|
| Go out | h | Focus on parent directory |
|-------------|------|------------------------------------------------|
| Go out plus | H | Focus on parent directory plus extra action |
|-------------|------|------------------------------------------------|
| Go to mark | ' | Jump to bookmark (waits for single key id) |
|-------------|------|------------------------------------------------|
| Set mark | m | Set bookmark (waits for single key id) |
|-------------|------|------------------------------------------------|
| Reset | <BS> | Reset current explorer |
|-------------|------|------------------------------------------------|
| Reveal cwd | @ | Reset current current working directory |
|-------------|------|------------------------------------------------|
| Show help | g? | Show help window |
|-------------|------|------------------------------------------------|
| Synchronize | = | Synchronize user edits and/or external changes |
|-------------|------|------------------------------------------------|
| Trim left | < | Trim left part of branch |
|-------------|------|------------------------------------------------|
| Trim right | > | Trim right part of branch |
|-------------|------|------------------------------------------------|
<
Details:
- "Go in":
- Always opens file in the latest window before `MiniFiles.open()` call.
- Never closes explorer.
- Works in linewise Visual mode to expand multiple entries.
- "Go in plus" is regular "Go in" but closes explorer after opening a file.
- "Go out plus" is regular "Go out" but trims right part of branch.
- "Set mark" and "Go to mark" both wait for user to press a single character
of a bookmark id. Example: `ma` sets directory path of focused window as
bookmark "a"; `'a` jumps (sets as whole branch) to bookmark "a".
Special bookmark "'" always points to path before the latest bookmark jump.
- "Reset" focuses only on "anchor" directory (the one used to open current
explorer) and resets all stored directory cursor positions.
- "Reveal cwd" extends branch to include |current-directory|.
If it is not an ancestor of the current branch, nothing is done.
- "Show help" results into new window with helpful information about current
explorer (like buffer mappings and bookmarks). Press `q` to close it.
- "Synchronize" parses user edits in directory buffers, applies them (after
confirmation), and updates all directory buffers with the most relevant
file system information. Can also be used without user edits to show up
to date file system entries.
See |MiniFiles-manipulation| for more info about file system manipulation.
- "Trim left" and "Trim right" trim parts of the whole branch, not only its
currently visible parts.
Notes:
- Each action has exported function with more details about it.
- Keys can be configured with `mappings` table of |MiniFiles.config|.
------------------------------------------------------------------------------
*MiniFiles-manipulation*
Manipulation ~
File system manipulation is done by editing text inside directory buffers,
which are shown inside dedicated window(s). See |MiniFiles-navigation| for
more information about navigating to a particular directory.
General workflow:
- Navigate to the directory in which manipulation should be done.
- Edit buffer in the way representing file system action.
- Repeat previous steps until all necessary file system actions are recorded.
Note: even if directory buffer is hidden, its modifications are preserved,
so you can navigate in and out of directory with modified buffer.
- Execute |MiniFiles.synchronize()| (default key is `=`). This will prompt
confirmation dialog listing all file system actions (per directory) it is
about to perform. READ IT CAREFULLY.
- Confirm by pressing `y` / `<CR>` (apply edits and update buffers) or
don't confirm by pressing `n` / `<Esc>` (update buffers without applying edits).
Note: prefer small and not related steps with more frequent synchronization
over single complex manipulation. There are (known) cases which won't work.
# How does it work ~
All manipulation functionality is powered by creating and keeping track of
path indexes: text of the form `/xxx` (`xxx` is the number path index) placed
at the start of every line representing file system entry.
By default they are hidden as concealed text (along with prefix separators)
for more convenience but you can see them by setting |conceallevel| to 0.
DO NOT modify text to the left of entry name.
During synchronization, actual text for entry name is compared to path index
at that line (if present) to deduce which file system action to perform.
Note that order of text manipulation steps does not affect performed actions.
# Supported file system actions ~
## Create ~
- Create file by creating new line with file name (including extension).
- Create directory by creating new line with directory name followed by `/`.
- Create file or directory inside nested directories by creating new line
with text like 'dir/nested-dir/' or 'dir/nested-dir/file'.
Always use `/` on any OS.
## Delete ~
- Delete file or directory by deleting **whole line** describing it.
- If `options.permanent_delete` is `true`, delete is permanent. Otherwise
file system entry is moved to a module-specific trash directory
(see |MiniFiles.config| for more details).
## Rename ~
- Rename file or directory by editing its name (not icon or path index to
the left of it).
- With default mappings for `h` / `l` it might be not convenient to rename
only part of an entry. You can adopt any of the following approaches:
- Use different motions, like |$|, |e|, |f|, etc.
- Go into Insert mode and navigate inside it.
- Change mappings to be more suited for manipulation and not navigation.
See "Mappings" section in |MiniFiles.config|.
- It is not needed to end directory name with `/`.
- Cyclic renames ("a" to "b" and "b" to "a") are not supported.
## Copy ~
- Copy file or directory by copying **whole line** describing it and pasting
it inside buffer of target directory.
- Change of target path is allowed. Edit only entry name in target location
(not icon or path index to the left of it).
- Copying inside same parent directory is supported only if target path has
different name.
- Copying inside child directory is supported.
## Move ~
- Move file or directory by cutting **whole line** describing it and then
pasting it inside target directory.
- Change of target path is allowed. Edit only entry name in target location
(not icon or path index to the left of it).
- Moving directory inside itself is not supported.
------------------------------------------------------------------------------
*MiniFiles-events*
Events ~
To allow user customization and integration of external tools, certain |User|
autocommand events are triggered under common circumstances.
UI events ~
- `MiniFilesExplorerOpen` - just after explorer finishes opening.
- `MiniFilesExplorerClose` - just before explorer starts closing.
- `MiniFilesBufferCreate` - when buffer is created to show a particular
directory. Triggered once per directory during one explorer session.
Can be used to create buffer-local mappings.
- `MiniFilesBufferUpdate` - when directory buffer is updated with new content.
Can be used for integrations to set |extmarks| with useful information.
- `MiniFilesWindowOpen` - when new window is opened. Can be used to set
window-local settings (like border, 'winblend', etc.)
- `MiniFilesWindowUpdate` - when a window is updated. Triggers VERY frequently.
At least after every cursor movement and "go in" / "go out" action.
Callback for each UI event will receive `data` field (see |nvim_create_autocmd()|)
with the following information:
- <buf_id> - index of target buffer.
- <win_id> - index of target window. Can be `nil`, like in
`MiniFilesBufferCreate` and buffer's first `MiniFilesBufferUpdate` as
they are triggered before window is created.
File action events ~
- `MiniFilesActionCreate` - after entry is successfully created.
- `MiniFilesActionDelete` - after entry is successfully deleted.
- `MiniFilesActionRename` - after entry is successfully renamed.
- `MiniFilesActionCopy` - after entry is successfully copied.
- `MiniFilesActionMove` - after entry is successfully moved.
Callback for each file action event will receive `data` field
(see |nvim_create_autocmd()|) with the following information:
- <action> - string with action name.
- <from> - full path of entry before action (`nil` for "create" action).
- <to> - full path of entry after action (`nil` for permanent "delete" action).
------------------------------------------------------------------------------
*MiniFiles-examples*
Common configuration examples ~
# Toggle explorer ~
Use a combination of |MiniFiles.open()| and |MiniFiles.close()|: >lua
local minifiles_toggle = function(...)
if not MiniFiles.close() then MiniFiles.open(...) end
end
<
# Customize windows ~
For most of the common customizations using `MiniFilesWindowOpen` event
autocommand is the suggested approach: >lua
vim.api.nvim_create_autocmd('User', {
pattern = 'MiniFilesWindowOpen',
callback = function(args)
local win_id = args.data.win_id
-- Customize window-local settings
vim.wo[win_id].winblend = 50
local config = vim.api.nvim_win_get_config(win_id)
config.border, config.title_pos = 'double', 'right'
vim.api.nvim_win_set_config(win_id, config)
end,
})
<
However, some parts (like window title and height) of window config are later
updated internally. Use `MiniFilesWindowUpdate` event for them: >lua
vim.api.nvim_create_autocmd('User', {
pattern = 'MiniFilesWindowUpdate',
callback = function(args)
local config = vim.api.nvim_win_get_config(args.data.win_id)
-- Ensure fixed height
config.height = 10
-- Ensure title padding
if config.title[#config.title][1] ~= ' ' then
table.insert(config.title, { ' ', 'NormalFloat' })
end
if config.title[1][1] ~= ' ' then
table.insert(config.title, 1, { ' ', 'NormalFloat' })
end
vim.api.nvim_win_set_config(args.data.win_id, config)
end,
})
<
# Customize icons ~
Use different directory icon (if you don't use |mini.icons|): >lua
local my_prefix = function(fs_entry)
if fs_entry.fs_type == 'directory' then
-- NOTE: it is usually a good idea to use icon followed by space
return ' ', 'MiniFilesDirectory'
end
return MiniFiles.default_prefix(fs_entry)
end
require('mini.files').setup({ content = { prefix = my_prefix } })
<
Show no icons: >lua
require('mini.files').setup({ content = { prefix = function() end } })
<
# Create mapping to show/hide dot-files ~
Create an autocommand for `MiniFilesBufferCreate` event which calls
|MiniFiles.refresh()| with explicit `content.filter` functions: >lua
local show_dotfiles = true
local filter_show = function(fs_entry) return true end
local filter_hide = function(fs_entry)
return not vim.startswith(fs_entry.name, '.')
end
local toggle_dotfiles = function()
show_dotfiles = not show_dotfiles
local new_filter = show_dotfiles and filter_show or filter_hide
MiniFiles.refresh({ content = { filter = new_filter } })
end
vim.api.nvim_create_autocmd('User', {
pattern = 'MiniFilesBufferCreate',
callback = function(args)
local buf_id = args.data.buf_id
-- Tweak left-hand side of mapping to your liking
vim.keymap.set('n', 'g.', toggle_dotfiles, { buffer = buf_id })
end,
})
<
# Create mappings to modify target window via split ~
Combine |MiniFiles.get_explorer_state()| and |MiniFiles.set_target_window()|: >lua
local map_split = function(buf_id, lhs, direction)
local rhs = function()
-- Make new window and set it as target
local cur_target = MiniFiles.get_explorer_state().target_window
local new_target = vim.api.nvim_win_call(cur_target, function()
vim.cmd(direction .. ' split')
return vim.api.nvim_get_current_win()
end)
MiniFiles.set_target_window(new_target)
-- This intentionally doesn't act on file under cursor in favor of
-- explicit "go in" action (`l` / `L`). To immediately open file,
-- add appropriate `MiniFiles.go_in()` call instead of this comment.
end
-- Adding `desc` will result into `show_help` entries
local desc = 'Split ' .. direction
vim.keymap.set('n', lhs, rhs, { buffer = buf_id, desc = desc })
end
vim.api.nvim_create_autocmd('User', {
pattern = 'MiniFilesBufferCreate',
callback = function(args)
local buf_id = args.data.buf_id
-- Tweak keys to your liking
map_split(buf_id, '<C-s>', 'belowright horizontal')
map_split(buf_id, '<C-v>', 'belowright vertical')
end,
})
<
# Create mappings which use data from entry under cursor ~
Use |MiniFiles.get_fs_entry()|: >lua
-- Set focused directory as current working directory
local set_cwd = function()
local path = (MiniFiles.get_fs_entry() or {}).path
if path == nil then return vim.notify('Cursor is not on valid entry') end
vim.fn.chdir(vim.fs.dirname(path))
end
-- Yank in register full path of entry under cursor
local yank_path = function()
local path = (MiniFiles.get_fs_entry() or {}).path
if path == nil then return vim.notify('Cursor is not on valid entry') end
vim.fn.setreg(vim.v.register, path)
end
vim.api.nvim_create_autocmd('User', {
pattern = 'MiniFilesBufferCreate',
callback = function(args)
local b = args.data.buf_id
vim.keymap.set('n', 'g~', set_cwd, { buffer = b, desc = 'Set cwd' })
vim.keymap.set('n', 'gy', yank_path, { buffer = b, desc = 'Yank path' })
end,
})
<
# Set custom bookmarks ~
Use |MiniFiles.set_bookmark()| inside `MiniFilesExplorerOpen` event: >lua
local set_mark = function(id, path, desc)
MiniFiles.set_bookmark(id, path, { desc = desc })
end
vim.api.nvim_create_autocmd('User', {
pattern = 'MiniFilesExplorerOpen',
callback = function()
set_mark('c', vim.fn.stdpath('config'), 'Config') -- path
set_mark('w', vim.fn.getcwd, 'Working directory') -- callable
set_mark('~', '~', 'Home directory')
end,
})
<
------------------------------------------------------------------------------
*MiniFiles.setup()*
`MiniFiles.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniFiles.config|.
Usage ~
>lua
require('mini.files').setup() -- use default config
-- OR
require('mini.files').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniFiles.config*
`MiniFiles.config`
Module config
Default values:
>lua
MiniFiles.config = {
-- Customization of shown content
content = {
-- Predicate for which file system entries to show
filter = nil,
-- What prefix to show to the left of file system entry
prefix = nil,
-- In which order to show file system entries
sort = nil,
},
-- Module mappings created only inside explorer.
-- Use `''` (empty string) to not create one.
mappings = {
close = 'q',
go_in = 'l',
go_in_plus = 'L',
go_out = 'h',
go_out_plus = 'H',
mark_goto = "'",
mark_set = 'm',
reset = '<BS>',
reveal_cwd = '@',
show_help = 'g?',
synchronize = '=',
trim_left = '<',
trim_right = '>',
},
-- General options
options = {
-- Whether to delete permanently or move into module-specific trash
permanent_delete = true,
-- Whether to use for editing directories
use_as_default_explorer = true,
},
-- Customization of explorer windows
windows = {
-- Maximum number of windows to show side by side
max_number = math.huge,
-- Whether to show preview of file/directory under cursor
preview = false,
-- Width of focused window
width_focus = 50,
-- Width of non-focused window
width_nofocus = 15,
-- Width of preview window
width_preview = 25,
},
}
<
# Content ~
`content.filter` is a predicate which takes file system entry data as input
and returns `true`-ish value if it should be shown.
Uses |MiniFiles.default_filter()| by default.
A file system entry data is a table with the following fields:
- <fs_type> `(string)` - one of "file" or "directory".
- <name> `(string)` - basename of an entry (including extension).
- <path> `(string)` - full path of an entry.
`content.prefix` describes what text (prefix) to show to the left of file
system entry name (if any) and how to highlight it. It also takes file
system entry data as input and returns tuple of text and highlight group
name to be used to highlight prefix. See |MiniFiles-examples| for common
examples of how to use it.
Note: due to how lines are parsed to detect user edits for file system
manipulation, output of `content.prefix` should not contain `/` character.
Uses |MiniFiles.default_prefix()| by default.
`content.sort` describes in which order directory entries should be shown
in directory buffer. Takes as input and returns as output an array of file
system entry data. Note: technically, it can be used to filter and modify
its elements as well.
Uses |MiniFiles.default_sort()| by default.
# Mappings ~
`mappings` table can be used to customize buffer-local mappings created in each
directory buffer for built-in actions. Entry name corresponds to the function
name of the action, value - right hand side of the mapping. Supply empty
string to not create a particular mapping.
Default mappings are mostly designed for consistent navigation experience.
Here are some alternatives: >lua
-- Close explorer after opening file with `l`
mappings = {
go_in = 'L',
go_in_plus = 'l',
}
-- Don't use `h`/`l` for easier cursor navigation during text edit
mappings = {
go_in = 'L',
go_in_plus = '',
go_out = 'H',
go_out_plus = '',
}
<
# Options ~
`options.use_as_default_explorer` is a boolean indicating whether this module
will be used as a default file explorer to edit directory (instead of |netrw|).
Note: to work with directory in |arglist|, do not lazy load this module.
`options.permanent_delete` is a boolean indicating whether to perform
permanent delete or move into special trash directory.
This is a module-specific variant of "remove to trash".
Target directory is 'mini.files/trash' inside standard path of Neovim data
directory (execute `:echo stdpath('data')` to see its path in your case).
# Windows ~
`windows.max_number` is a maximum number of windows allowed to be open
simultaneously. For example, use value 1 to always show single window.
There is no constraint by default.
`windows.preview` is a boolean indicating whether to show preview of
file/directory under cursor. Note: it is shown with highlighting if Neovim
version is sufficient and file is small enough (less than 1K bytes per line
or 1M bytes in total).
`windows.width_focus` and `windows.width_nofocus` are number of columns used
as `width` for focused and non-focused windows respectively.
------------------------------------------------------------------------------
*MiniFiles.open()*
`MiniFiles.open`({path}, {use_latest}, {opts})
Open file explorer
Common ways to use this function: >lua
-- Open current working directory in a last used state
MiniFiles.open()
-- Fresh explorer in current working directory
MiniFiles.open(nil, false)
-- Open directory of current file (in last used state) focused on the file
MiniFiles.open(vim.api.nvim_buf_get_name(0))
-- Fresh explorer in directory of current file
MiniFiles.open(vim.api.nvim_buf_get_name(0), false)
-- Open last used `path` (per tabpage)
-- Current working directory for the first time
MiniFiles.open(MiniFiles.get_latest_path())
<
Parameters ~
{path} `(string|nil)` A valid file system path used as anchor.
If it is a path to directory, used directly.
If it is a path to file, its parent directory is used as anchor while
explorer will focus on the supplied file.
Default: path of |current-directory|.
{use_latest} `(boolean|nil)` Whether to load explorer state from history
(based on the supplied anchor path). Default: `true`.
{opts} `(table|nil)` Table of options overriding |MiniFiles.config| and
`vim.b.minifiles_config` for this particular explorer session.
------------------------------------------------------------------------------
*MiniFiles.refresh()*
`MiniFiles.refresh`({opts})
Refresh explorer
Notes:
- If in `opts` at least one of `content` entry is not `nil`, all directory
buffers are forced to update.
Parameters ~
{opts} `(table|nil)` Table of options to update.
------------------------------------------------------------------------------
*MiniFiles.synchronize()*
`MiniFiles.synchronize`()
Synchronize explorer
- Parse user edits in directory buffers.
- Convert edits to file system actions and apply them after confirmation.
Choosing "No" skips application while "Cancel" stops synchronization.
- Update all directory buffers with the most relevant file system information.
Can be used without user edits to account for external file system changes.
Return ~
`(boolean)` Whether synchronization was done.
------------------------------------------------------------------------------
*MiniFiles.reset()*
`MiniFiles.reset`()
Reset explorer
- Show single window focused on anchor directory (which was used as first
argument for |MiniFiles.open()|).
- Reset all tracked directory cursors to point at first entry.
------------------------------------------------------------------------------
*MiniFiles.close()*
`MiniFiles.close`()
Close explorer
Return ~
`(boolean|nil)` Whether closing was done or `nil` if there was nothing to close.
------------------------------------------------------------------------------
*MiniFiles.go_in()*
`MiniFiles.go_in`({opts})
Go in entry under cursor
Depends on entry under cursor:
- If directory, focus on it in the window to the right.
- If file, open it in the window which was current during |MiniFiles.open()|.
Explorer is not closed after that.
Parameters ~
{opts} `(table|nil)` Options. Possible fields:
- <close_on_file> `(boolean)` - whether to close explorer after going
inside a file. Powers the `go_in_plus` mapping.
Default: `false`.
------------------------------------------------------------------------------
*MiniFiles.go_out()*
`MiniFiles.go_out`()
Go out to parent directory
- Focus on window to the left showing parent of current directory.
------------------------------------------------------------------------------
*MiniFiles.trim_left()*
`MiniFiles.trim_left`()
Trim left part of branch
- Remove all branch paths to the left of currently focused one. This also
results into current window becoming the most left one.
------------------------------------------------------------------------------
*MiniFiles.trim_right()*
`MiniFiles.trim_right`()
Trim right part of branch
- Remove all branch paths to the right of currently focused one. This also
results into current window becoming the most right one.
------------------------------------------------------------------------------
*MiniFiles.reveal_cwd()*
`MiniFiles.reveal_cwd`()
Reveal current working directory
- Prepend branch with parent paths until current working directory is reached.
Do nothing if not inside it.
------------------------------------------------------------------------------
*MiniFiles.show_help()*
`MiniFiles.show_help`()
Show help window
- Open window with helpful information about currently shown explorer and
focus on it. To close it, press `q`.
------------------------------------------------------------------------------
*MiniFiles.get_fs_entry()*
`MiniFiles.get_fs_entry`({buf_id}, {line})
Get file system entry data
Parameters ~
{buf_id} `(number|nil)` Buffer identifier of valid directory buffer.
Default: current buffer.
{line} `(number|nil)` Line number of entry for which to return information.
Default: cursor line.
Return ~
`(table|nil)` Table of file system entry data with the following fields:
- <fs_type> `(string)` - one of "file" or "directory".
- <name> `(string)` - basename of an entry (including extension).
- <path> `(string)` - full path of an entry.
Returns `nil` if there is no proper file system entry path at the line.
------------------------------------------------------------------------------
*MiniFiles.get_explorer_state()*
`MiniFiles.get_explorer_state`()
Get state of active explorer
Return ~
`(table|nil)` Table with explorer state data or `nil` if no active explorer.
State data is a table with the following fields:
- <anchor> `(string)` - anchor directory path (see |MiniFiles.open()|).
- <bookmarks> `(table)` - map from bookmark id (single character) to its data:
table with <path> and <desc> fields (see |MiniFiles.set_bookmark()|).
- <branch> `(table)` - array of nested paths for currently opened branch.
- <depth_focus> `(number)` - an index in <branch> for currently focused path.
- <target_window> `(number)` - identifier of target window.
- <windows> `(table)` - array with data about currently opened windows.
Each element is a table with <win_id> (window identifier) and <path> (path
shown in the window) fields.
See also ~
- |MiniFiles.set_bookmark()|
- |MiniFiles.set_branch()|
- |MiniFiles.set_target_window()|
------------------------------------------------------------------------------
*MiniFiles.set_target_window()*
`MiniFiles.set_target_window`({win_id})
Set target window
Parameters ~
{win_id} `(number)` Window identifier inside which file will be opened.
------------------------------------------------------------------------------
*MiniFiles.set_branch()*
`MiniFiles.set_branch`({branch}, {opts})
Set branch
Set which paths to display. Preview (if enabled) is applied afterwards.
Parameters ~
{branch} `(table)` Array of strings representing actually present on disk paths.
Each consecutive pair should represent direct parent-child paths.
Should contain at least one directory path.
May end with file path (will be previwed).
Relative paths are resolved using |current-directory|.
{opts} `(table|nil)` Options. Possible fields:
- <depth_focus> `(number)` - an index in `branch` for path to focus. Will
be normalized to fit inside `branch`. Default: index of deepest directory.
See also ~
|MiniFiles.get_explorer_state()|
------------------------------------------------------------------------------
*MiniFiles.set_bookmark()*
`MiniFiles.set_bookmark`({id}, {path}, {opts})
Set bookmark
Parameters ~
{id} `(string)` Single character bookmark id.
{path} `(string|function)` Path of a present on disk directory to set as
a bookmark's path. If callable, should return such path.
{opts} `(table|nil)` Options. Possible fields:
- <desc> `(string)` - bookmark description (used in help window).
------------------------------------------------------------------------------
*MiniFiles.get_latest_path()*
`MiniFiles.get_latest_path`()
Get latest used anchor path
Note: if latest used `path` argument for |MiniFiles.open()| was for file,
this will return its parent (as it was used as anchor path).
------------------------------------------------------------------------------
*MiniFiles.default_filter()*
`MiniFiles.default_filter`({fs_entry})
Default filter of file system entries
Currently does not filter anything out.
Parameters ~
{fs_entry} `(table)` Table with the following fields:
- <fs_type> `(string)` - one of "file" or "directory".
- <name> `(string)` - basename of an entry (including extension).
- <path> `(string)` - full path of an entry.
Return ~
`(boolean)` Always `true`.
------------------------------------------------------------------------------
*MiniFiles.default_prefix()*
`MiniFiles.default_prefix`({fs_entry})
Default prefix of file system entries
- If |MiniIcons| is set up, use |MiniIcons.get()| for "directory"/"file" category.
- Otherwise:
- For directory return fixed icon and "MiniFilesDirectory" group name.
- For file try to use `get_icon()` from 'nvim-tree/nvim-web-devicons'.
If missing, return fixed icon and 'MiniFilesFile' group name.
Parameters ~
{fs_entry} `(table)` Table with the following fields:
- <fs_type> `(string)` - one of "file" or "directory".
- <name> `(string)` - basename of an entry (including extension).
- <path> `(string)` - full path of an entry.
Return ~
`(...)` Icon and highlight group name. For more details, see |MiniFiles.config|
and |MiniFiles-examples|.
------------------------------------------------------------------------------
*MiniFiles.default_sort()*
`MiniFiles.default_sort`({fs_entries})
Default sort of file system entries
Sort directories and files separately (alphabetically ignoring case) and
put directories first.
Parameters ~
{fs_entries} `(table)` Array of file system entry data.
Each one is a table with the following fields:
- <fs_type> `(string)` - one of "file" or "directory".
- <name> `(string)` - basename of an entry (including extension).
- <path> `(string)` - full path of an entry.
Return ~
`(table)` Sorted array of file system entries.
vim:tw=78:ts=8:noet:ft=help:norl: