Skip to content
Navigation Menu
{{ message }}
-
Notifications
You must be signed in to change notification settings - Fork 70
Expand file tree
/
Copy pathctrlspace.txt
More file actions
1662 lines (1217 loc) · 65.4 KB
/
Copy pathctrlspace.txt
File metadata and controls
1662 lines (1217 loc) · 65.4 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
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*ctrlspace.txt* For Vim version 7.3+ Last change: 2020.12.01
*ctrlspace*
*vim-ctrlspace*
Vim-CtrlSpace 5.0.7~
Vim Space Controller
Copyright (c) 2013-2020 Szymon Wrozynski and Contributors
==========================================================================
Table of Contents *ctrlspace-toc*
1. Overview |ctrlspace-overview|
2. Idea by Analogy |ctrlspace-idea|
3. Getting Started |ctrlspace-getting-started|
3.1 Installation |ctrlspace-installation|
3.2 Basic Settings |ctrlspace-basic-settings|
3.2.1 Go Engine |ctrlspace-go-engine|
3.2.2 Symbols |ctrlspace-symbols|
3.2.3 Glob Command |ctrlspace-glob-command|
3.2.4 Search Timing |ctrlspace-search-timing|
3.2.5 Colors |ctrlspace-colors|
3.3 First Steps |ctrlspace-first-steps|
4. User Interface |ctrlspace-ui|
4.1 Status Line |ctrlspace-status-line|
4.2 Tabline |ctrlspace-tabline|
4.3 Project Root |ctrlspace-project-root|
5. Lists |ctrlspace-lists|
5.1 Buffer List |ctrlspace-buffer-list|
5.1.1 Single Mode |ctrlspace-single-mode|
5.1.2 Visible Mode |ctrlspace-visible-mode|
5.1.3 All Mode |ctrlspace-all-mode|
5.2 File List |ctrlspace-file-list|
5.3 Tab List |ctrlspace-tab-list|
5.4 Workspace List |ctrlspace-workspace-list|
5.5 Bookmark List |ctrlspace-bookmark-list|
6. Common Modes |ctrlspace-common-modes|
6.1 Zoom Mode |ctrlspace-zoom-mode|
6.2 Next Tab Mode |ctrlspace-next-tab-mode|
6.3 Search Mode |ctrlspace-search-mode|
6.4 Nop Mode |ctrlspace-nop-mode|
6.5 Help Mode |ctrlspace-help-mode|
7. Configuration |ctrlspace-configuration|
7.1 g:CtrlSpaceHeight |g:CtrlSpaceHeight|
7.2 g:CtrlSpaceMaxHeight |g:CtrlSpaceMaxHeight|
7.3 g:CtrlSpaceSetDefaultMapping |g:CtrlSpaceSetDefaultMapping|
7.4 g:CtrlSpaceDefaultMappingKey |g:CtrlSpaceDefaultMappingKey|
7.5 g:CtrlSpaceKeys |g:CtrlSpaceKeys|
7.6 g:CtrlSpaceHelp |g:CtrlSpaceHelp|
7.7 g:CtrlSpaceGlobCommand |g:CtrlSpaceGlobCommand|
7.8 g:CtrlSpaceEnableFilesCache |g:CtrlSpaceEnableFilesCache|
7.9 g:CtrlSpaceUseTabline |g:CtrlSpaceUseTabline|
7.10 g:CtrlSpaceUseArrowsInTerm |g:CtrlSpaceUseArrowsInTerm|
7.11 g:CtrlSpaceUseMouseAndArrowsInTerm
|g:CtrlSpaceUseMouseAndArrowsInTerm|
7.12 g:CtrlSpaceSaveWorkspaceOnExit |g:CtrlSpaceSaveWorkspaceOnExit|
7.13 g:CtrlSpaceSaveWorkspaceOnSwitch |g:CtrlSpaceSaveWorkspaceOnSwitch|
7.14 g:CtrlSpaceLoadLastWorkspaceOnStart
|g:CtrlSpaceLoadLastWorkspaceOnStart|
7.15 g:CtrlSpaceEnableBufferTabWrapAround
|g:CtrlSpaceEnableBufferTabWrapAround|
7.16 g:CtrlSpaceCacheDir |g:CtrlSpaceCacheDir|
7.17 g:CtrlSpaceProjectRootMarkers |g:CtrlSpaceProjectRootMarkers|
7.18 g:CtrlSpaceUseUnicode |g:CtrlSpaceUseUnicode|
7.19 g:CtrlSpaceSymbols |g:CtrlSpaceSymbols|
7.20 g:CtrlSpaceIgnoredFiles |g:CtrlSpaceIgnoredFiles|
7.21 g:CtrlSpaceStatuslineFunction |g:CtrlSpaceStatuslineFunction|
7.22 g:CtrlSpaceSearchTiming |g:CtrlSpaceSearchTiming|
7.23 g:CtrlSpaceFileEngine |g:CtrlSpaceFileEngine|
7.24 g:CtrlSpaceSortHelp |g:CtrlSpaceSortHelp|
7.25 g:CtrlSpaceWorkspaceFile |g:CtrlSpaceWorkspaceFile|
8. API |ctrlspace-api|
8.1 Commands |ctrlspace-commands|
8.1.1 :CtrlSpace [keys] |:CtrlSpace|
8.1.2 :CtrlSpaceGoUp |:CtrlSpaceGoUp|
8.1.3 :CtrlSpaceGoDown |:CtrlSpaceGoDown|
8.1.4 :CtrlSpaceTabLabel |:CtrlSpaceTabLabel|
8.1.5 :CtrlSpaceClearTabLabel |:CtrlSpaceClearTabLabel|
8.1.6 :CtrlSpaceSaveWorkspace [workspace] |:CtrlSpaceSaveWorkspace|
8.1.7 :CtrlSpaceNewWorkspace |:CtrlSpaceNewWorkspace|
8.1.8 :CtrlSpaceLoadWorkspace [!] [workspace] |:CtrlSpaceLoadWorkspace|
8.1.9 :CtrlSpaceAddProjectRoot [dir] |:CtrlSpaceAddProjectRoot|
8.1.10 :CtrlSpaceRemoveProjectRoot [dir] |:CtrlSpaceRemoveProjectRoot|
8.2 Functions |ctrlspace-functions|
8.2.1 ctrlspace#api#BufferList({tabnr}) |ctrlspace#api#BufferList()|
8.2.2 ctrlspace#api#Buffers({tabnr}) |ctrlspace#api#Buffers()|
8.2.3 ctrlspace#api#TabModified({tabnr}) |ctrlspace#api#TabModified()|
8.2.4 ctrlspace#api#Statusline() |ctrlspace#api#Statusline()|
8.2.5 ctrlspace#api#StatuslineTabSegment()
|ctrlspace#api#StatuslineTabSegment()|
8.2.6 ctrlspace#api#StatuslineModeSegment({...})
|ctrlspace#api#StatuslineModeSegment()|
8.2.7 ctrlspace#api#TabBuffersNumber({tabnr})
|ctrlspace#api#TabBuffersNumber()|
8.2.8 ctrlspace#api#TabTitle({tabnr}, {bufnr}, {bufname})
|ctrlspace#api#TabTitle()|
8.2.9 ctrlspace#api#Guitablabel() |ctrlspace#api#Guitablabel()|
8.2.10 ctrlspace#api#Tabline() |ctrlspace#api#Tabline()|
8.2.11 ctrlspace#api#TabList() |ctrlspace#api#TabList()|
8.2.12 ctrlspace#api#BufNr() |ctrlspace#api#BufNr()|
9. File Engine Specifications |ctrlspace-engine-specs|
10. FAQ |ctrlspace-FAQ|
11. Authors and License |ctrlspace-authors-and-license|
==========================================================================
1. Overview *ctrlspace-overview*
Welcome to Vim-CtrlSpace, a comprehensive solution for your Vim editor
providing:
* tabs / buffers / files management
* fast fuzzy searching powered by Go
* workspaces (sessions)
* bookmarks for your favorite projects
The plugin name follows the convention of naming fuzzy search plugins
after their default mappings (like Command-T or CtrlP), hence the plugin
mapping is by default `Ctrl` + `Space`.
If you have already starred this repo, thank you!
If you have a question, a feature request, or a new
idea, don't hesitate to post new issues or pull requests.
Collaboration is the most awesome thing in the open source community!
|ctrlspace-toc|
==========================================================================
2. Idea by Analogy *ctrlspace-idea*
Vim-CtrlSpace interface is a window you can invoke by pressing <C-Space>.
The window displays a list of items. You can select those items with <j>,
<k>, and <CR> keys.
Generally speaking Vim-CtrlSpace can display 5 types of lists:
* Buffer List
* File List
* Tab List
* Workspace List
* Bookmark List
Lists can be explained with a simple analogy. Let's imagine Vim is a
writing desk. Your projects are like drawers. The Bookmark List simply
displays your favorite projects.
To get documents from a drawer you would need a File List. It allows you
to easily look up contents of a given project. Once you locate and pick up
a file it becomes a buffer.
A buffer is like a sheet of paper lying on the desk. Sometimes you can
have a blank piece of paper – that's a new unsaved buffer. It would become
eventually a file on the disk once saved (put into a drawer). To manage
all buffers on the desk you would need a Buffer List.
So far our analogy is fairly simple. This workflow is straightforward but
inefficient in the long run with a large amount of files. How could we
optimize it?
The answer are tabs – a secret weapon of Vim-CtrlSpace. Each tab holds a
separate list of buffers. And this is something very different when
compared to plain Vim. Tabs powered by the plugin can be seen as piles of
documents on the desk.
With tabs you can, for example:
* group related buffers
* extract to other tabs
* name them accordingly
* move or copy them
Tabs usage in Vim-CtrlSpace is quite more extensive than in Vim. This is
because they serve mainly as independent buffer lists, so you are likely
to have plenty of them. Tabs can be accessed and managed within Tab List.
All your buffers, tabs, and tab layouts can be persisted as a workspace.
It's like taking a picture of your desk with an instant camera. You can
save multiple workspaces per project with Workspace List.
|ctrlspace-toc|
==========================================================================
3. Getting Started *ctrlspace-getting-started*
|ctrlspace-toc|
--------------------------------------------------------------------------
3.1 Installation *ctrlspace-installation*
If you use Vundle add to your `.vimrc`: >
Plugin 'vim-ctrlspace/vim-ctrlspace'
<
You can also clone the repository to your `.vim` directory: >
cd ~/.vim
git clone https://github.com/vim-ctrlspace/vim-ctrlspace.git .
<
|ctrlspace-toc|
--------------------------------------------------------------------------
3.2 Basic Settings *ctrlspace-basic-settings*
First please make sure that you set `nocompatible` and `hidden` options,
and set `encoding=utf-8` (as required by the plugin) in your `.vimrc`: >
set nocompatible
set hidden
set encoding=utf-8
<
If you feel brave enough turn off tabline: >
set showtabline=0
<
Tabline in Vim has very limited capabilities and as Vim-CtrlSpace makes
use of tabs intensively, tabline would just get in your way. Tab List
(<l>) makes tabline obsolete ;).
|ctrlspace-toc|
--------------------------------------------------------------------------
3.2.1 Go Engine *ctrlspace-go-engine*
The plugin provides engine compiled for popular operating systems and
architectures. By default it will attempt to detect your os and
architecture. To see if auto detection was successful press <?>.
To find more about file engines check |g:CtrlSpaceFileEngine|.
|ctrlspace-toc|
--------------------------------------------------------------------------
3.2.2 Symbols *ctrlspace-symbols*
Vim-Ctrlspace displays icons in the UI if your font supports UTF8, or
ASCII characters as a fallback. Some symbols (glyphs) might not look well
with the font you are using, so feel free to change and adjust them.
This is the config I use for Inconsolata font in MacVim: >
if has("gui_running")
" Settings for MacVim and Inconsolata font
let g:CtrlSpaceSymbols = { "File": "◯", "CTab": "▣", "Tabs": "▢" }
endif
<
Since it's impossible to provide universal character set that would look
well on any machine, therefore the fine tuning is left up to you.
You can find more about this tuning option in the plugin help:
|g:CtrlSpaceSymbols|.
If you feel that you have found a better symbol for a given view, you are
more than welcome to open a pull request.
|ctrlspace-toc|
--------------------------------------------------------------------------
3.2.3 Glob Command *ctrlspace-glob-command*
Another important setting is the Glob command (|g:CtrlSpaceGlobCommand|).
This command is used to collect all files in your project directory.
Specifically, I recommend that you install and use `ag`, as it respects
`.gitignore` rules and is really fast. Once it's installed you can add
this line to your `.vimrc`: >
if executable("ag")
let g:CtrlSpaceGlobCommand = 'ag -l --nocolor -g ""'
endif
<
|ctrlspace-toc|
--------------------------------------------------------------------------
3.2.4 Search Timing *ctrlspace-search-timing*
If you usually have to deal with huge projects having 100 000 files you
can increase plugin fuzzy search delay to make it even more responsible by
providing a higher |g:CtrlSpaceSearchTiming| value: >
let g:CtrlSpaceSearchTiming = 500
<
|ctrlspace-toc|
--------------------------------------------------------------------------
3.2.5 Colors *ctrlspace-colors*
Finally, you can adjust some plugin colors. By default plugin uses
the following setup: >
hi link CtrlSpaceNormal PMenu
hi link CtrlSpaceSelected PMenuSel
hi link CtrlSpaceSearch Search
hi link CtrlSpaceStatus StatusLine
<
However some color schemes show search results with the same colors as
PMenu groups. If that's your case try to link CtrlSpaceSearch highlight
group to IncSearch instead: >
hi link CtrlSpaceSearch IncSearch
<
Of course nothing prevents you from providing your own highlighting, for
example: >
hi CtrlSpaceSearch guifg=#cb4b16 guibg=NONE gui=bold
\ ctermfg=9 ctermbg=NONE term=bold cterm=bold
<
|ctrlspace-toc|
--------------------------------------------------------------------------
3.3 First Steps *ctrlspace-first-steps*
Alright! You've hopefully installed, configured Vim-CtrlSpace, and
restarted Vim (otherwise do it!). Now you're wondering how to start using
this thing.
First, you need to select a project. Vim operates in a directory,
described as `CWD` (Current Working Directory). If you've just started a
MacVim it's probably pointing to your home directory (issue |:pwd| to
check it).
I advise you to add a project to the Bookmark List by opening the plugin
window (<C-Space>) and pressing <b>. The plugin will ask for a project
directory.
Make sure that the path is not home directory. Otherwise the plugin will
start indexing all your files which will be pointless and resource
exhaustive. Be concrete and provide a real path to a project. Once your
bookmark is created, you can go there with <CR>.
Now open some files with <o>. Finally save a workspace with <w> by
providing your first workspace name.
For key reference press <?> inside the plugin window.
|ctrlspace-toc|
==========================================================================
4. User Interface *ctrlspace-ui*
Vim-CtrlSpace contains 5 different lists: Buffer List, File List, Tab
List, Workspace List, and Bookmark List. Some of those have additional
modes. However, in a modal editor like Vim this should not fear you ;).
You can jump between lists easily by pressing one of the following keys:
| Key | Action |
| --- | ----------------------------------------------------- |
| `h` | Toggle Buffer List (aka `H`ome List) |
| `H` | Jump to Buffer List (aka `H`ome List) with Search Mode |
| `o` | Toggle File List (aka `O`pen List) |
| `O` | Jump to File List (aka `O`pen List) with Search Mode |
| `l` | Toggle Tab List (aka `L`ists List) |
| `L` | Jump to Tab List (aka `L`ists List) with Search Mode |
| `w` | Toggle `W`orkspace List |
| `W` | Jump to `W`orkspace List with Search Mode |
| `b` | Toggle `B`ookmark List |
| `B` | Jump to `B`ookmark List with Search Mode |
Anytime you can return by pressing <BS>.
User interface of the plugin is a window with a list view.
Its status line contains important symbolic information:
| UTF8 | ASCII | List | Description |
| ---- | ----- | ----------- | ------------------------- |
| `⌗` | `#` | All | Vim-CtrlSpace logo symbol |
| `?` | `?` | All | Help Mode indicator |
| `›_‹` | `[_]` | All | Search Mode indicator |
| `•` | `SIN` | Buffer | Single Mode indicator |
| `★` | `VIS` | Buffer | Visible Mode indicator |
| `፨` | `ALL` | Buffer | All Mode indicator |
| `○` | `FILE` | File | File List indicator |
| `⁺²` | `+2` | Buffer/File | Next Tab Mode indicator |
| `⌕` | `*` | Buffer/File | Zoom Mode indicator |
| `▫▪▫` | `-+-` | Tab | Tab List indicator |
| `⬆` | `|*|` | Workspace | Workspace Load Mode |
| `⬇` | `[*]` | Workspace | Workspace Save Mode |
| `♥` | `BM` | Bookmark | Bookmark List indicator |
Items listed in the plugin window can have additional indicators
(following the item text):
| UTF8 | ASCII | Indicator |
| ---- | ----- | --------------------------------- |
| `+` | `+` | Item modified |
| `★` | `*` | Item active |
| `☆` | `-` | Item visible or previously active |
Those indicators can be configured via |g:CtrlSpaceSymbols| variable.
|ctrlspace-toc|
--------------------------------------------------------------------------
4.1 Status Line *ctrlspace-status-line*
Vim-CtrlSpace requires a status bar. If you are using a plugin customizing
the status bar this might be a bit tricky. For example `vim-airline`
(https://github.com/bling/vim-airline) plugin might require you to set
option: >
let g:airline_exclude_preview = 1
<
`LightLine` (https://github.com/itchyny/lightline.vim) will require to use
custom status line segments, provided by Vim-CtrlSpace API.
|ctrlspace-toc|
--------------------------------------------------------------------------
4.2 Tabline *ctrlspace-tabline*
Vim-CtrlSpace can set a custom tabline for you, if |g:CtrlSpaceUseTabline|
is enabled. Tabs in the tabline are displayed in the following way
(similar format is used also in the Tab List):
| Format | Tab number | Buffers | Modified | Buffer or tab name |
| ------ | ---------- | ------- | -------- | ------------------ |
| UTF8 | `1` | `²` | `+` | `[README.md]` |
| ASCII | `1` | `:2` | `+` | `[README.md]` |
If GUI tabs are detected, this option will also set the proper function to
|guitablabel|.
Intensive tabs usage makes the tabline feature less usable, because window
can only display limited amount of tabs especially with long names.
Tab List is a solution to that problem so you can even turn off the
tabline completely: >
set showtabline=0
<
To see Tab List press <l> in the plugin window.
|ctrlspace-toc|
--------------------------------------------------------------------------
4.3 Project Root *ctrlspace-project-root*
Some plugin features require a project directory to work properly. If you
open the File List for the first time in a given Vim working directory
(CWD) it will try to figure out the possible project root directory.
First, it starts in the Vim current working directory and checks for so
called "root markers". The root markers are characteristic directories
that are available in an exemplary project root directory (like `.git` or
`.hg`...). You can define them yourself in the
|g:CtrlSpaceProjectRootMarkers| variable.
If no markers were found the plugin will check if CWD is a known root. The
known roots are those directories you provided (accepted) yourself.
If the current directory is not a project root the algorithm will repeat
the whole procedure in the parent directory.
After checking all parent directories plugin will ask you to provide the
root folder explicitly. After your acceptance your choice will be stored
permanently in the `.cs_cache` file.
The `.cs_cache` file is created inside a folder specified by
|g:CtrlSpaceCacheDir|. By default it's set to your home directory
If you add a directory to bookmarks, it will be considered as a project
root automatically. Interestingly bookmarks are stored in the same cache
file.
|ctrlspace-toc|
==========================================================================
5. Lists *ctrlspace-lists*
CtrlSpace has 5 lists:
* Buffer List (<h> for Home)
* File List (<o> for Open)
* Tab List (<l> for Lists)
* Workspace List (<w>)
* Bookmark List (<b>)
To open CtrlSpace window press <C-Space>. By default Buffer List will
open. Keys <h>, <o>, <l>, <w>, <b> when pressed again toggle between
current and previous list. Similarly <BS> works the same way.
|ctrlspace-toc|
--------------------------------------------------------------------------
5.1 Buffer List *ctrlspace-buffer-list*
Displays buffers from:
* the current tab (Single Mode)
* visible buffers (Visible Mode <*>)
* all available buffers (All Mode <a>)
Buffers in Vim can have various "properties". The plugin displays only
certain buffers: "listed" (|buflisted|) and named ones. Unnamed buffers are
diplayed only when visible in the current tab or contain unsaved changes
(|modified|). This restriction prevents from accidentally diplaying
technical buffers of other plugins - not intended to be shown.
|ctrlspace-toc|
--------------------------------------------------------------------------
5.1.1 Single Mode *ctrlspace-single-mode*
| UTF8 | ASCII |
| ---- | ----- |
| `•` | `SIN` |
Displays only buffers related to the current tab. By related I mean
precisely "seen by (or shown in) this tab at least once". Such related
buffers are present in a buffer list kept by this tab (and available in
the Single Mode). The Single name refers to the fact we are browsing only
a list of this tab.
You can also "forget" a buffer by pressing <f>. Forgetting means
detaching, making unrelated, or just making foreign to the given tab. Such
buffer might be related to other tabs instead or might be unrelated to any
tab. Then it would only be available through the "All Mode" (press <a>).
Forgotten buffers unrelated to any tab are called "foreign buffers". They
can be automatically deleted (closed) by pressing <F>. You can also
collect them in an automatic tab by pressing <f> in the Tab List.
|ctrlspace-toc|
--------------------------------------------------------------------------
5.1.2 Visible Mode *ctrlspace-visible-mode*
| UTF8 | ASCII |
| ---- | ----- |
| `★` | `VIS` |
Narrows down Single Mode to only visible buffers. For example if you have
3 files in the tab and window is vertically split (displaying two files)
only those 2 files will be displayed in the list.
You can easily move between visible windows with <Tab>. By <S-Tab> you can
move to window and go back to the plugin. This action results in changing
the active window on which plugin will operate.
|ctrlspace-toc|
--------------------------------------------------------------------------
5.1.3 All Mode *ctrlspace-all-mode*
| UTF8 | ASCII |
| ---- | ----- |
| `፨` | `ALL` |
Displays buffers from all tabs together with foreign buffers. Practically
it displays all possible buffers similarly to |:ls| command.
|ctrlspace-toc|
--------------------------------------------------------------------------
5.2 File List *ctrlspace-file-list*
| UTF8 | ASCII |
| ---- | ----- |
| `○` | `FILE` |
Displays all files in the project starting from project root
(|ctrlspace-project-root|). If the file you are looking for is not
immediately visible on the list press </> to toggle fuzzy-search mode
(|ctrlspace-search-mode|).
To have the most recent list of files press <r> (refresh). If you switch
git branches don't forget to refresh the list.
Troubleshooting~
If you happen to see lots of files from the outside your current project,
for example all your files from home directory, probably you set by an
accident a root mark in your home directory. To fix that, open
`~/.cs_cache` and remove bookmark and project root entries that were
added by mistake.
|ctrlspace-toc|
--------------------------------------------------------------------------
5.3 Tab List *ctrlspace-tab-list*
| UTF8 | ASCII |
| ---- | ----- |
| `▫▪▫` | `-+-` |
Tabs in Vim-CtrlSpace are considered as lists of related buffers still
remaining regular Vim tab pages. They can display buffers in split
windows, be moved, copied, deleted, named, extracted, switched, and so on.
The plugin lets you perform many classic tab actions easily in the Tab
List by pressing letter <l> (for `L`ists - since tab pages are simply
seperate buffer lists).
Tabs, due to this plugin nature, are used more extensively than in a
typical Vim usage. Vim author, Bram Moolenaar in his great talk "7 Habits
of Effective Text Editing" (http://www.youtube.com/watch?v=p6K4iIMlouI)
stated that if you needed more than 10 tabs then probably you were doing
something wrong. This in not the case in Vim-CtrlSpace where tab pages are
labelled containers for buffers.
Therefore the default tabline used in Vim for organizing tab pages is not
sufficient. For example, you might have more tabs with long labels which
don't fit the tabline width, causing rendering problems.
It's recommended to turn off the tabline entirely (via Vim |showtabline|
option) and stick only to the Tab List.
Tabs can be (re)named (<=> or <m>, and <_>). Labelled tabs containing more
than one buffer can be closed (<c>) after a confirmation (except automatic
tabs). Automatic tabs are labelled tabs created automatically by the
plugin as a result of copying (<y>), collecting unsaved buffers (<u>), or
collecting foreign buffers (<f>).
|ctrlspace-toc|
--------------------------------------------------------------------------
5.4 Workspace List *ctrlspace-workspace-list*
| UTF8 | ASCII | Mode |
| ---- | ----- | --------- |
| `⬆` | `|*|` | Load Mode |
| `⬇` | `[*]` | Save mode |
The plugin allows you to save and load workspaces. A workspace is a set of
opened windows, tabs, and buffers. The Workspace List shows you available
workspaces for a given project. By default this list is displayed in the
Load Mode. To open Workspace List press <w>. Then press <s> to select the
mode (toggles between Save and Load modes), <m>, <=> to rename, and <d> to
delete.
The word "workspace" can be considered a synonym of a "session" and all
your buffers, tabs, and tab layouts are persisted. It's like taking a
picture of your desk with an instant camera.
You can save multiple workspaces per project with Workspace List.
The ability of having so many sessions available at hand creates a lot of
interesting use cases! For example, you can have a workspace for each task
or feature you are working on. It's very easy to switch from one workspace
to another.
You can easily append any workspace to your current one (press <a>).
Moreover, you can have special workspaces prepared to be appended to
others. In that way you are able to reuse common and repetative sets of
tabs and files in many contexts.
Workspaces are saved in a file (`.cs_workspaces`) inside the project
directory. Its exact name and path is determined by configuration.
It's also possible to automatically load the last active workspace on Vim
startup and save active workspace on Vim exit. See
|g:CtrlSpaceLoadLastWorkspaceOnStart| and |g:CtrlSpaceSaveWorkspaceOnExit|
for more details.
|ctrlspace-toc|
--------------------------------------------------------------------------
5.5 Bookmark List *ctrlspace-bookmark-list*
| UTF8 | ASCII |
| ---- | ----- |
| `♥` | `BM` |
Bookmark List can be treated as a favorite project list. With bookmarks
you can easily jump between different directory locations (changes Vim
CWD).
Each project directory contains naturally a different file list, different
workspace list, etc. Nothing prevents you to mix buffers between various
projects - you can, for example jump to previous project, open a
configuration file, and return to your current stuff with that file open.
To see the Bookmark List press <b>. To add a bookmark - press <a>, to edit
the target directory - <e>. You can also rename it with <m> and <=>.
It's worth to mention, that you can still navigate to different places
manually, with the |:cd| command. The plugin will behave the same way.
In fact, jumping with Bookmark List is just like a shortcut for the |:cd|
command.
Cool Tip~
Another smart way of changing directory is jumping to a directory of given
buffer (file) by pressing <i> in the Buffer List. It's useful if you have
files from two or more different projects. To go (jump) back press <I>.
|ctrlspace-toc|
==========================================================================
6. Common Modes *ctrlspace-common-modes*
Common modes are available in more than one list.
|ctrlspace-toc|
--------------------------------------------------------------------------
6.1 Zoom Mode *ctrlspace-zoom-mode*
| UTF8 | ASCII |
| ---- | ----- |
| `⌕` | `*` |
Zoom Mode works for Buffer and File Lists. To toggle Zoom Mode on press
<z>. Then press <Space> to maximize buffer that is highlighted in the
list. Pressing <Space> doesn't add buffer to the current tab – if you want
to add it press <CR>. To exit Zoom Mode press <z> again.
When entering Zoom Mode your current position and list is remembered and
reverted on exiting.
|ctrlspace-toc|
--------------------------------------------------------------------------
6.2 Next Tab Mode *ctrlspace-next-tab-mode*
| UTF8 | ASCII |
| ---- | ----- |
| `⁺²` | `+2` |
Similarly like the Zoom Mode, Next Tab Mode works in File and Buffer
Lists. It can be turned on with the uppercase <T> letter (or <C-t>). If
the mode is active, <T> creates the new tab only once (that would be a
next tab to the current one) and add all files / buffers to that tab. This
is opposite to <t> which opens things in a new tab every time. If you
want to create a new tab but stay in the Next Tab Mode press <C-t>.
The mode indicator shows you the number of buffers opened in the next tab.
You can jump to that tab anytime with <]> key.
This mode allows for bulk opening files or buffers in subsequent tabs.
That way you can easily extract given items to separate tabs.
|ctrlspace-toc|
--------------------------------------------------------------------------
6.3 Search Mode *ctrlspace-search-mode*
| UTF8 | ASCII |
| ---- | ----- |
| `›_‹` | `[_]` |
This mode can be triggered by </> or by a capital letter of given list
(<H>, <O>, <L>, <W>, <B>). In that mode you can enter a search text. This
will narrow the list content and sort items by relevance (the highest
score - the lowest position). To finish entering press <CR> or </>. If you
press <Tab> instead, your text will be accepted and followed immediately
(just like pressing <CR> twice). To see full key reference during query
entering press <?>.
To clear the search query press <BS>. To use previous queries from history
press <C-p> (previous) or <C-n> (next).
|ctrlspace-toc|
--------------------------------------------------------------------------
6.4 Nop Mode *ctrlspace-nop-mode*
Nop (Non-Operational) Mode happens when for example there are no items to
show (empty list). This might also happen while typing a search query and
there are no results at all.
In Nop Mode the keys are limited just to a subset of common keys. To see
what keys are available check <?>.
|ctrlspace-toc|
--------------------------------------------------------------------------
6.5 Help Mode *ctrlspace-help-mode*
Help Mode is a view showing available keys together with their
descriptions, depending on your current list and modes. You can toggle
Help Mode in any view by pressing <?>.
|ctrlspace-toc|
==========================================================================
7. Configuration *ctrlspace-configuration*
Vim-CtrlSpace has many configuration options. To alter any of them, define
it as global variables in your `.vimrc` file in the similar form: >
let g:CtrlSpaceFooBar = 123
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.1 *g:CtrlSpaceHeight*
Sets the minimal height of the plugin window. Default value: >
let g:CtrlSpaceHeight = 1
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.2 *g:CtrlSpaceMaxHeight*
Sets the maximum height of the plugin window. If `0` is provided it uses 1/3
of the screen height. Default value: >
let g:CtrlSpaceMaxHeight = 0
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.3 *g:CtrlSpaceSetDefaultMapping*
Turns on the default mapping. If you turn off this option (`0`) you will
have to provide your own mapping to trigger the plugin. Default value: >
let g:CtrlSpaceSetDefaultMapping = 1
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.4 *g:CtrlSpaceDefaultMappingKey*
By default, Vim-CtrlSpace maps itself to <C-Space>. If you want to change
the default mapping provide it here as a string with valid Vim keystroke
notation. Default value: >
let g:CtrlSpaceDefaultMappingKey = "<C-Space>"
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.5 *g:CtrlSpaceKeys*
You can provide your own functions and override default key bindings in
that way. The |g:CtrlSpaceKeys| can store a dictionary, where keys could be
lists or modes, accordingly:
* `"Search"`
* `"Help"`
* `"Nop"`
* `"Buffer"`
* `"File"`
* `"Tab"`
* `"Workspace"`
* `"Bookmark"`
Values are dictionaries with key mappings and function names. Look at the
following example: >
function! PrintFooBar(k)
echo "Foo Bar!"
endfunction
let g:CtrlSpaceKeys = { "Buffer": { "a": "PrintFooBar" } }
<
This will map a function `PrintFooBar(k)` to key <a> in the buffer list.
Besides key mappings there are also available some special key classes:
* `"lowercase"`
* `"uppercase"`
* `"controls"`
* `"numbers"`
* `"specials"`
Default value: >
let g:CtrlSpaceKeys = {}
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.6 *g:CtrlSpaceHelp*
Allows you to provide a help description for your custom functions.
Contains a dictionary with keys holding function names and values
containing their descriptions. They will be displayed in the Help
Mode. Example: >
let g:CtrlSpaceHelp = { "PrintFooBar": "Print foo bar!" }
<
Default value: >
let g:CtrlSpaceHelp = {}
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.7 *g:CtrlSpaceGlobCommand*
If not empty, the provided command will be used to list all files instead
of Vim |globpath()| function. For example, if you have `Ag` installed that
could be: >
if executable("ag")
let g:CtrlSpaceGlobCommand = 'ag -l --nocolor -g ""'
endif
<
Default value: >
let g:CtrlSpaceGlobCommand = ""
<
Cool Tip~
You can even make `Ag` to show hidden files by providing `--hidden` option: >
let g:CtrlSpaceGlobCommand = 'ag -l --hidden --nocolor -g ""'
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.8 *g:CtrlSpaceEnableFilesCache*
Enable to store a cache file (cs_files) inside .git/ of each project. More
suited for very large projects (>10k+ files at least, likely even more).
Disable to load project files by simply re-globbing each time FILE mode is
activated. More suited for small to medium sized projects, or for projects
where switching to branches with different file layouts is common.
Supported globbers are: rg, fd & ag (auto-detected in that order)
Default value: >
let g:CtrlSpaceEnableFilesCache = 1
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.9 *g:CtrlSpaceUseTabline*
Should Vim-CtrlSpace change your default tabline to its own?
Default value: >
let g:CtrlSpaceUseTabline = 1
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.10 *g:CtrlSpaceUseArrowsInTerm*
Should the plugin use arrows and <Home>, <End>, <PageUp>, <PageDown> keys
in a terminal Vim.
Default value: >
let g:CtrlSpaceUseArrowsInTerm = 0
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.11 *g:CtrlSpaceUseMouseAndArrowsInTerm*
Should the plugin use mouse, arrows and <Home>, <End>, <PageUp>,
<PageDown> keys in a terminal Vim. Disables the <Esc> key if turned on.
Default value: >
let g:CtrlSpaceUseMouseAndArrowsInTerm = 0
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.12 *g:CtrlSpaceSaveWorkspaceOnExit*
Saves the active workspace (if present) on Vim quit. If this option is
set, the Vim quit (<Q>) action in the plugin does not check for workspace
changes.
Default value: >
let g:CtrlSpaceSaveWorkspaceOnExit = 0
<
|ctrlspace-toc|
--------------------------------------------------------------------------
7.13 *g:CtrlSpaceSaveWorkspaceOnSwitch*
Saves the active workspace (if present) on switching to another workspace
or clearing (closing) the current one. If this option is set, the plugin
won't warn you about an unsaved workspace.
Default value: >
let g:CtrlSpaceSaveWorkspaceOnSwitch = 0
<
|ctrlspace-toc|
--------------------------------------------------------------------------
You can’t perform that action at this time.
