/
session.txt
836 lines (678 loc) · 36.4 KB
/
session.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
*session.txt* Extended session management for Vim
===============================================================================
Contents ~
1. Introduction |session-introduction|
2. Installation |session-installation|
3. Commands |session-commands|
1. The |:SaveSession| command
2. The |:OpenSession| command
3. The |:RestartVim| command
4. The |:CloseSession| command
5. The |:DeleteSession| command
6. The |:ViewSession| command
7. Tab scoped sessions |tab-scoped-sessions|
1. The |:OpenTabSession| command
2. The |:SaveTabSession| command
3. The |:AppendTabSession| command
4. The |:CloseTabSession| command
4. Options |session-options|
1. The |sessionoptions| setting
2. The |g:session_directory| option
3. The |g:session_default_name| option
4. The |g:session_default_overwrite| option
5. The |g:session_extension| option
6. The |g:session_autoload| option
7. The |g:session_autosave| option
8. The |g:session_autosave_periodic| option
9. The |g:session_verbose_messages| option
10. The |g:session_default_to_last| option
11. The |g:session_persist_globals| option
12. The |g:session_restart_environment| option
13. The |g:session_command_aliases| option
14. The |g:session_menu| option
15. The |g:loaded_session| option
5. Compatibility with other plug-ins |session-compatibility-with-other-plug-ins|
6. Known issues |session-known-issues|
7. Function reference |session-function-reference|
1. Public API for the vim-session plug-in |public-api-for-vim-session-plug-in|
1. The |xolox#session#save_session()| function
2. The |xolox#session#save_globals()| function
3. The |xolox#session#save_features()| function
4. The |xolox#session#save_colors()| function
5. The |xolox#session#save_fullscreen()| function
6. The |xolox#session#save_qflist()| function
7. The |xolox#session#save_state()| function
8. The |xolox#session#save_special_windows()| function
9. The |xolox#session#auto_load()| function
10. The |xolox#session#auto_save()| function
11. The |xolox#session#auto_save_periodic()| function
12. The |xolox#session#auto_unlock()| function
13. The |xolox#session#prompt_for_name()| function
14. The |xolox#session#name_to_path()| function
15. The |xolox#session#path_to_name()| function
16. The |xolox#session#get_names()| function
17. The |xolox#session#complete_names()| function
18. The |xolox#session#is_tab_scoped()| function
19. The |xolox#session#find_current_session()| function
20. The |xolox#session#get_label()| function
21. The |xolox#session#options_include()| function
22. The |xolox#session#include_tabs()| function
23. The |xolox#session#change_tab_options()| function
24. The |xolox#session#restore_tab_options()| function
8. Contact |session-contact|
9. License |session-license|
10. Sample session script |sample-session-script|
11. References |session-references|
===============================================================================
*session-introduction*
Introduction ~
The vim-session plug-in improves upon Vim's built-in |:mksession| command by
enabling you to easily and (if you want) automatically persist and restore your
Vim editing sessions. It works by generating a Vim |script| that restores your
current settings and the arrangement of tab pages and/or split windows and the
files they contain.
To persist your current editing session you can execute the |:SaveSession|
command. If you don't provide a name for the session 'default' is used (you can
change this name with an option). You're free to use whatever characters you
like in session names. When you want to restore your session simply execute
|:OpenSession|. Again the name 'default' is used if you don't provide one. When
a session is active, has been changed and you quit Vim you'll be prompted
whether you want to save the open session before quitting Vim:
Image: Screenshot of auto-save prompt (see reference [1])
If you want, the plug-in can also automatically save your session every few
minutes (see the |g:session_autosave_periodic| option). When you start Vim
without editing any files and the default session exists, you'll be prompted
whether you want to restore the default session:
Image: Screenshot of auto-open prompt (see reference [2])
When you start Vim with a custom server name (see |--servername|) that matches
one of the existing session names then the matching session will be
automatically restored. For example I use several sessions to quickly edit my
Vim plug-ins:
>
$ gvim --servername easytags-plugin
$ gvim --servername session-plugin
$ # etc.
<
The session scripts created by this plug-in are stored in the directory
'~/.vim/sessions' (on UNIX) or '~\vimfiles\sessions' (on Windows) but you can
change the location by setting |g:session_directory|. If you're curious what
the session scripts generated by vim-session look like see the sample below
[3].
If you're still getting to know the plug-in, the "Sessions" menu may help: It
contains menu items for most commands defined by the plug-in.
===============================================================================
*session-installation*
Installation ~
_Please note that the vim-session plug-in requires my vim-misc plug-in which is
separately distributed._
Unzip the most recent ZIP archives of the vim-session [4] and vim-misc [5]
plug-ins inside your Vim profile directory (usually this is '~/.vim' on UNIX
and '%USERPROFILE%\vimfiles' on Windows), restart Vim and execute the command
':helptags ~/.vim/doc' (use ':helptags ~\vimfiles\doc' instead on Windows). To
get started execute ':Note' or ':edit note:', this will start a new note that
contains instructions on how to continue from there (and how to use the plug-in
in general).
If you prefer you can also use Pathogen [6], Vundle [7] or a similar tool to
install & update the vim-session [8] and vim-misc [9] plug-ins using a local
clone of the git repository.
After you've installed the plug-in and restarted Vim, the following commands
will be available to you:
===============================================================================
*session-commands*
Commands ~
Note that environment variables inside command arguments are expanded by the
plug-in.
-------------------------------------------------------------------------------
The *:SaveSession* command
This command saves your current editing session just like Vim's built-in
|:mksession| command does. The difference is that you don't pass a full
pathname as argument but just a name, any name really. Press '<Tab>' to get
completion of existing session names. If you don't provide an argument the
default session name is used, unless an existing session is open in which case
the name of that session will be used.
If the session you're trying to save is already active in another Vim instance
you'll get a warning and nothing happens. You can use a bang (!) as in
':SaveSession! ...' to ignore the warning and save the session anyway.
Your session script will be saved in the directory pointed to by the
|g:session_directory| option.
-------------------------------------------------------------------------------
The *:OpenSession* command
This command is basically |:source| in disguise, but it supports tab completion
of session names and it executes |:CloseSession| before opening the session.
When you don't provide a session name and only a single session exists then
that session is opened, otherwise the plug-in will ask you to select one from a
list:
>
Please select the session to restore:
1. vim-profile
2. session-plugin
3. etc.
Type number and <Enter> or click with mouse (empty cancels):
<
If the session you're trying to open is already active in another Vim instance
you'll get a warning and nothing happens. You can use a bang (!) as in
':OpenSession! ...' to ignore the warning and open the session anyway.
Note also that when you use a bang (!) right after the command name existing
tab pages and windows are closed, discarding any changes in the files you were
editing!
-------------------------------------------------------------------------------
The *:RestartVim* command
This command saves your current editing session, restarts Vim and restores your
editing session. This can come in handy when you're debugging Vim scripts which
can't be easily/safely reloaded using a more lightweight approach [10]. It
should work fine on Windows and UNIX alike but because of technical limitations
it only works in graphical Vim.
Any commands following the |:RestartVim| command are intercepted and executed
after Vim is restarted and your session has been restored. This makes it easy
to perform manual tests which involve restarting Vim, e.g. ':RestartVim | edit
/path/to/file | call MyTest()'.
-------------------------------------------------------------------------------
The *:CloseSession* command
This command closes all but the current tab page and window and then edits a
new, empty buffer. If a session is loaded when you execute this command the
plug-in will first ask you whether you want to save that session.
Note that when you use a bang (!) right after the command name existing tab
pages and windows are closed, discarding any changes in the files you were
editing!
-------------------------------------------------------------------------------
The *:DeleteSession* command
Using this command you can delete any of the sessions created by this plug-in.
If the session you are trying to delete is currently active in another Vim
instance you'll get a warning and nothing happens. You can use a bang (!) as in
':DeleteSession! ...' to ignore the warning and delete the session anyway.
Note that this command only deletes the session script, it leaves your open tab
pages and windows exactly as they were.
-------------------------------------------------------------------------------
The *:ViewSession* command
Execute this command to view the Vim script generated for a session. This
command is useful when you need to review the generated Vim script repeatedly,
for example while debugging or modifying the vim-session plug-in.
-------------------------------------------------------------------------------
*tab-scoped-sessions*
Tab scoped sessions ~
When |'sessionoptions'| contains 'tabpages' (this is the default) session
scripts will persist and restore all windows in all tab pages. When you remove
'tabpages' from |'sessionoptions'| you get a sort of light-weight sessions:
They are constrained to a single tab page. Vim's |:mksession| command and the
vim-session plug-in both fully support this.
You can change |'sessionoptions'| in your |vimrc| script but then you can never
save a session including tab pages. To decide on the spot whether you want a
global or tab scoped session, the vim-session plug-in defines the three
commands documented below.
Note that tab scoped sessions are regular session scripts, so when you load a
tab scoped session using |:OpenSession| instead of |:OpenTabSession| the vim-
session plug-in _assumes_ it is a global session and will close all active tab
pages before opening the tab scoped session.
-------------------------------------------------------------------------------
The *:OpenTabSession* command
Just like |:OpenSession| but applies only to the current tab page.
-------------------------------------------------------------------------------
The *:SaveTabSession* command
Just like |:SaveSession| but applies only to the current tab page.
-------------------------------------------------------------------------------
The *:AppendTabSession* command
This command opens a new tab page and loads the given tab scoped session in
that tab page. You can give this command a count just like |:tabnew|.
-------------------------------------------------------------------------------
The *:CloseTabSession* command
Just like |:CloseSession| but applies only to the current tab page.
===============================================================================
*session-options*
Options ~
The following Vim options and plug-in options (global variables) can be used to
configure the plug-in to your preferences.
-------------------------------------------------------------------------------
The *sessionoptions* setting
Because the vim-session plug-in uses Vim's |:mksession| command you can change
how it works by setting |'sessionoptions'| in your |vimrc| script, for example:
>
" If you only want to save the current tab page:
set sessionoptions-=tabpages
" If you don't want help windows to be restored:
set sessionoptions-=help
<
Note that the vim-session plug-in automatically and unconditionally executes
the following change just before saving a session:
>
" Don't persist options and mappings because it can corrupt sessions.
set sessionoptions-=options
<
-------------------------------------------------------------------------------
The *g:session_directory* option
This option controls the location of your session scripts. Its default value is
'~/.vim/sessions' (on UNIX) or '~\vimfiles\sessions' (on Windows). If you don't
mind the default you don't have to do anything; the directory will be created
for you. Note that a leading '~' is expanded to your current home directory
('$HOME' on UNIX, '%USERPROFILE%' on Windows).
-------------------------------------------------------------------------------
The *g:session_default_name* option
The name of the default session without directory or filename extension (you'll
never guess what the default is).
-------------------------------------------------------------------------------
The *g:session_default_overwrite* option
If you set this to true (1), every Vim instance without an explicit session
loaded will overwrite the default session (the last Vim instance wins).
-------------------------------------------------------------------------------
The *g:session_extension* option
The filename extension of session scripts. This should include the dot that
separates the basename from the extension. Defaults to '.vim'.
-------------------------------------------------------------------------------
The *g:session_autoload* option
By default this option is set to "'prompt'". This means that when you start Vim
without opening any files and the default session script exists, the session
plug-in will ask whether you want to restore your default session. When you set
this option to "'yes'" and you start Vim without opening any files the default
session will be restored without a prompt. To completely disable automatic
loading you can set this option to "'no'".
-------------------------------------------------------------------------------
The *g:session_autosave* option
By default this option is set to "'prompt'". When you've opened a session and
you quit Vim, the session plug-in will ask whether you want to save the changes
to your session. Set this option to "'yes'" to always automatically save open
sessions when you quit Vim. To completely disable automatic saving you can set
this option to "'no'".
-------------------------------------------------------------------------------
The *g:session_autosave_periodic* option
This option sets the interval in minutes for automatic, periodic saving of
active sessions. The default is zero which disables the feature.
Note that when the plug-in automatically saves a session (because you enabled
this feature) the plug-in will not prompt for your permission.
-------------------------------------------------------------------------------
The *g:session_verbose_messages* option
The session load/save prompts are quite verbose by default because they explain
how to disable the prompts. If you find the additional explanation distracting
you can lower the verbosity by setting this option to 0 (false) in your |vimrc|
script.
-------------------------------------------------------------------------------
The *g:session_default_to_last* option
By default this option is set to false (0). When you set this option to true
(1) and you start Vim, the session plug-in will open your last used session
instead of the default session. Note that the session plug-in will still show
you the dialog asking whether you want to restore the last used session. To get
rid of the dialog you have to set |g:session_autoload| to "'yes'".
-------------------------------------------------------------------------------
The *g:session_persist_globals* option
The vim-session plug-in uses Vim's |:mksession| command but it changes
|'sessionoptions'| so that Vim options and mappings are not persisted. The
plug-in does this because persistence of options and mappings can break loading
of sessions, in other words it's fragile (in my opinion).
If you want the plug-in to persist specific global variables or options you can
add their names to the list |g:session_persist_globals| in your |vimrc| script:
>
" Persist the value of the global option 'makeprg'.
let g:session_persist_globals = ['&makeprg']
<
Because the |vimrc| script is loaded before the plug-in you have to define the
list yourself. To persist multiple values:
>
" Persist all options related to :make.
let g:session_persist_globals = ['&makeprg', '&makeef']
<
Here's how you persist global variables: (in this case the variables of the
session plug-in itself :-)
>
" Persist the options of the session plug-in using the session plug-in...
let g:session_persist_globals = ['&sessionoptions']
call add(g:session_persist_globals, 'g:session_autoload')
call add(g:session_persist_globals, 'g:session_autosave')
call add(g:session_persist_globals, 'g:session_default_to_last')
call add(g:session_persist_globals, 'g:session_persist_globals')
<
The example above doesn't persist the |g:session_directory| variable because
this variable is used before loading a session script so persisting it inside
the session script is pointless.
-------------------------------------------------------------------------------
The *g:session_restart_environment* option
This option is a list of environment variable names (without the dollar signs)
that the |:RestartVim| command will pass on to the new instance of Vim. This
option is only useful on UNIX. By default the three environment variables
'$TERM', '$VIM' and '$VIMRUNTIME' are included in this list.
-------------------------------------------------------------------------------
The *g:session_command_aliases* option
The names of the commands defined by the session plug-in start with the action
they perform, followed by the string 'Session'. Some people prefer it the other
way around because they find it easier to remember and you can type
':Session<Tab>' to get completion of all available commands (actually this
works with the other style as well if you type ':*Session<Tab>' but I digress).
If you are one of those people you can enable this option in your |vimrc|
script like this:
>
:let g:session_command_aliases = 1
<
When this option is enabled the session plug-in will define the following
command aliases:
- 'SessionOpen' is an alias for 'OpenSession'
- 'SessionView' is an alias for 'ViewSession'
- 'SessionSave' is an alias for 'SaveSession'
- 'SessionDelete' is an alias for 'DeleteSession'
- 'SessionClose' is an alias for 'CloseSession'
Then there are the command aliases for tab scoped sessions:
- 'SessionTabOpen' is an alias for 'OpenTabSession'
- 'SessionTabSave' is an alias for 'SaveTabSession'
- 'SessionTabAppend' is an alias for 'AppendTabSession'
- 'SessionTabClose' is an alias for 'CloseTabSession'
The aliases support tab completion just like the real commands; they're exactly
the same except for the names.
When you enable the aliases, the default command names will still be available.
If you really don't like them, feel free to delete them using |:delcommand|.
-------------------------------------------------------------------------------
The *g:session_menu* option
By default the plug-in installs a top level menu. If you don't like this you
can disable it by adding the following line to your |vimrc| script:
>
:let g:session_menu = 0
<
-------------------------------------------------------------------------------
The *g:loaded_session* option
This variable isn't really an option but if you want to avoid loading the vim-
session plug-in you can set this variable to any value in your |vimrc| script:
>
:let g:loaded_session = 1
<
===============================================================================
*session-compatibility-with-other-plug-ins*
Compatibility with other plug-ins ~
Vim's |:mksession| command isn't really compatible with plug-ins that create
buffers with generated content and because of this the vim-session plug-in
includes specific workarounds for a couple of popular plug-ins:
- BufExplorer [11], Conque Shell [12], NERD tree [13], Project [14] and
taglist [15] windows are supported;
- When shell.vim [16] is installed Vim's full-screen state is persisted;
- The netrw (see |netrw-start|) plug-in supports sessions out of the box.
If your favorite plug-in doesn't work with the vim-session plug-in drop me a
mail and I'll see what I can do. Please include a link to the plug-in in your
e-mail so that I can install and test the plug-in.
===============================================================================
*session-known-issues*
Known issues ~
Recently this plug-in switched from reimplementing |:mksession| to actually
using it because this was the only way to support complex split window layouts.
Only after making this change did I realize |:mksession| doesn't support
|quickfix| and location list (see |location-list|) windows and of course it
turns out that bolting on support for these after the fact is going to
complicate the plug-in significantly (in other words, I'm working on it but it
might take a while...)
===============================================================================
*session-function-reference*
Function reference ~
The documentation of the 34 functions below was extracted from 1 Vim scripts on
June 18, 2014 at 22:49.
-------------------------------------------------------------------------------
*public-api-for-vim-session-plug-in*
Public API for the vim-session plug-in ~
-------------------------------------------------------------------------------
The *xolox#session#save_session()* function
Save the current Vim editing session to a Vim script using the |:mksession|
command and some additional Vim magic provided by the vim-session plug-in. When
the generated session script is later sourced using the |:source| command
(possibly in another process or even on another machine) it will restore the
editing session to its previous state (provided all of the files involved in
the session are still there at their original locations).
The first argument is expected to be a list, it will be extended with the lines
to be added to the session script. The second argument is expected to be the
filename under which the script will later be saved (it's embedded in a comment
at the top of the script).
-------------------------------------------------------------------------------
The *xolox#session#save_globals()* function
Serialize the values of the global variables configured by the user with the
|g:session_persist_globals| option. The first argument is expected to be a
list, it will be extended with the lines to be added to the session script.
-------------------------------------------------------------------------------
The *xolox#session#save_features()* function
Save the current state of the following Vim features:
- Whether syntax highlighting is enabled (':syntax on')
- Whether file type detection is enabled (':filetype on')
- Whether file type plug-ins are enabled (':filetype plugin on')
- Whether file type indent plug-ins are enabled (':filetype indent on')
The first argument is expected to be a list, it will be extended with the lines
to be added to the session script.
-------------------------------------------------------------------------------
The *xolox#session#save_colors()* function
Save the current color scheme and background color. The first argument is
expected to be a list, it will be extended with the lines to be added to the
session script.
-------------------------------------------------------------------------------
The *xolox#session#save_fullscreen()* function
Save the full screen state of Vim. This function provides integration between
my vim-session [17] and vim-shell [18] plug-ins. The first argument is expected
to be a list, it will be extended with the lines to be added to the session
script.
-------------------------------------------------------------------------------
The *xolox#session#save_qflist()* function
Save the contents of the quick-fix list. The first argument is expected to be a
list, it will be extended with the lines to be added to the session script.
-------------------------------------------------------------------------------
The *xolox#session#save_state()* function
Wrapper for the |:mksession| command that slightly massages the generated Vim
script to get rid of some strange quirks in the way Vim generates sessions.
Also implements support for buffers with content that was generated by other
Vim plug-ins. The first argument is expected to be a list, it will be extended
with the lines to be added to the session script.
-------------------------------------------------------------------------------
The *xolox#session#save_special_windows()* function
Implements support for buffers with content that was generated by other Vim
plug-ins. The first argument is expected to be a list, it will be extended with
the lines to be added to the session script.
-------------------------------------------------------------------------------
The *xolox#session#auto_load()* function
Automatically load the default or last used session when Vim starts. Normally
called by the |VimEnter| automatic command event.
-------------------------------------------------------------------------------
The *xolox#session#auto_save()* function
Automatically save the current editing session when Vim is closed. Normally
called by the |VimLeavePre| automatic command event.
-------------------------------------------------------------------------------
The *xolox#session#auto_save_periodic()* function
Automatically saves the current editing session every few minutes. Normally
called by the |CursorHold| and |CursorHoldI| automatic command events.
-------------------------------------------------------------------------------
The *xolox#session#auto_unlock()* function
Automatically unlock all sessions when Vim quits. Normally called by the
|VimLeavePre| automatic command event.
-------------------------------------------------------------------------------
The *xolox#session#prompt_for_name()* function
Prompt the user to select one of the existing sessions. The first argument is
expected to be a string describing what will be done to the session once it's
been selected. Returns the name of the selected session as a string. If no
session is selected an empty string is returned. Here's an example of what the
prompt looks like:
>
:call xolox#session#prompt_for_name('trash')
Please select the session to trash:
1. first-session
2. second-session
3. third-session
Type number and <Enter> or click with mouse (empty cancels):
<
If only a single session exists there's nothing to choose from so the name of
that session will be returned directly, without prompting the user.
-------------------------------------------------------------------------------
The *xolox#session#name_to_path()* function
Convert the name of a session (the first argument, expected to be a string) to
an absolute pathname. Any special characters in the session name will be
encoded using URL encoding. This means you're free to use whatever naming
conventions you like (regardless of special characters like slashes). Returns a
string.
-------------------------------------------------------------------------------
The *xolox#session#path_to_name()* function
Convert the absolute pathname of a session script (the first argument, expected
to be a string) to a session name. This function assumes the absolute pathname
refers to the configured session directory, but it does not check for it nor
does it require it (it simple takes the base name of the absolute pathname of
the session script and decodes it). Returns a string.
-------------------------------------------------------------------------------
The *xolox#session#get_names()* function
Get the names of all available sessions. This scans the directory configured
with |g:session_directory| for files that end with the suffix configured with
|g:session_extension|, takes the base name of each file and decodes any URL
encoded characters. Returns a list of strings.
-------------------------------------------------------------------------------
The *xolox#session#complete_names()* function
Completion function for user defined Vim commands. Used by commands like
|:OpenSession| and |:DeleteSession| to support user friendly completion.
-------------------------------------------------------------------------------
The *xolox#session#is_tab_scoped()* function
Determine whether the current session is tab scoped or global. Returns 1 (true)
when the session is tab scoped, 0 (false) otherwise.
-------------------------------------------------------------------------------
The *xolox#session#find_current_session()* function
Find the name of the current tab scoped or global session. Returns a string. If
no session is active an empty string is returned.
-------------------------------------------------------------------------------
The *xolox#session#get_label()* function
Get a human readable label based on the scope (tab scoped or global) and name
of a session. The first argument is the name (a string) and the second argument
is a boolean indicating the scope of the session; 1 (true) means tab scoped and
0 (false) means global scope. Returns a string.
-------------------------------------------------------------------------------
The *xolox#session#options_include()* function
Check whether Vim's sessionoptions (see |'sessionoptions'|) option includes the
keyword given as the first argument (expected to be a string). Returns 1 (true)
when it does, 0 (false) otherwise.
-------------------------------------------------------------------------------
The *xolox#session#include_tabs()* function
Check whether Vim's sessionoptions (see |'sessionoptions'|) option includes the
'tabpages' keyword. Returns 1 (true) when it does, 0 (false) otherwise.
-------------------------------------------------------------------------------
The *xolox#session#change_tab_options()* function
Temporarily change Vim's sessionoptions (see |'sessionoptions'|) option so we
can save a tab scoped session. Saves a copy of the original value to be
restored later.
-------------------------------------------------------------------------------
The *xolox#session#restore_tab_options()* function
Restore the original value of Vim's sessionoptions (see |'sessionoptions'|)
option.
===============================================================================
*session-contact*
Contact ~
If you have questions, bug reports, suggestions, etc. the author can be
contacted at peter@peterodding.com. The latest version is available at
http://peterodding.com/code/vim/session/ and http://github.com/xolox/vim-
session. If you like the script please vote for it on Vim Online [19].
===============================================================================
*session-license*
License ~
This software is licensed under the MIT license [20]. Š 2014 Peter Odding
<peter@peterodding.com>.
===============================================================================
*sample-session-script*
Sample session script ~
Here's an example session script generated by the vim-session plug-in while I
was editing the plug-in itself in Vim:
>
" ~/.vim/sessions/example.vim: Vim session script.
" Created by session.vim on 30 August 2010 at 05:26:28.
" Open this file in Vim and run :source % to restore your session.
set guioptions=aegit
set guifont=Monaco\ 13
if exists('g:syntax_on') != 1 | syntax on | endif
if exists('g:did_load_filetypes') != 1 | filetype on | endif
if exists('g:did_load_ftplugin') != 1 | filetype plugin on | endif
if exists('g:did_indent_on') != 1 | filetype indent on | endif
if !exists('g:colors_name') || g:colors_name != 'slate' | colorscheme slate | endif
call setqflist([])
let SessionLoad = 1
if &cp | set nocp | endif
let s:so_save = &so | let s:siso_save = &siso | set so=0 siso=0
let v:this_session=expand("<sfile>:p")
silent only
cd ~/Development/Vim/vim-session
if expand('%') == '' && !&modified && line('$') <= 1 && getline(1) == ''
let s:wipebuf = bufnr('%')
endif
set shortmess=aoO
badd +473 ~/Development/Vim/vim-session/autoload.vim
badd +1 ~/Development/Vim/vim-session/README.md
badd +1 ~/Development/Vim/vim-session/session.vim
badd +1 ~/Development/Vim/vim-session/TODO.md
set lines=43 columns=167
edit ~/Development/Vim/vim-session/README.md
set splitbelow splitright
set nosplitbelow
set nosplitright
wincmd t
set winheight=1 winwidth=1
argglobal
let s:l = 28 - ((27 * winheight(0) + 21) / 42)
if s:l < 1 | let s:l = 1 | endif
exe s:l
normal! zt
28
normal! 0
tabedit ~/Development/Vim/vim-session/TODO.md
set splitbelow splitright
set nosplitbelow
set nosplitright
wincmd t
set winheight=1 winwidth=1
argglobal
let s:l = 6 - ((5 * winheight(0) + 21) / 42)
if s:l < 1 | let s:l = 1 | endif
exe s:l
normal! zt
6
normal! 0
tabedit ~/Development/Vim/vim-session/session.vim
set splitbelow splitright
set nosplitbelow
set nosplitright
wincmd t
set winheight=1 winwidth=1
argglobal
let s:l = 17 - ((16 * winheight(0) + 21) / 42)
if s:l < 1 | let s:l = 1 | endif
exe s:l
normal! zt
17
normal! 014l
tabedit ~/Development/Vim/vim-session/autoload.vim
set splitbelow splitright
set nosplitbelow
set nosplitright
wincmd t
set winheight=1 winwidth=1
argglobal
let s:l = 473 - ((41 * winheight(0) + 21) / 42)
if s:l < 1 | let s:l = 1 | endif
exe s:l
normal! zt
473
normal! 018l
tabnext 4
if exists('s:wipebuf')
silent exe 'bwipe ' . s:wipebuf
endif
unlet! s:wipebuf
set winheight=1 winwidth=1 shortmess=filnxtToO
let s:sx = expand("<sfile>:p:r")."x.vim"
if file_readable(s:sx)
exe "source " . fnameescape(s:sx)
endif
let &so = s:so_save | let &siso = s:siso_save
doautoall SessionLoadPost
unlet SessionLoad
<
===============================================================================
*session-references*
References ~
[1] http://peterodding.com/code/vim/session/autosave.png
[2] http://peterodding.com/code/vim/session/autoopen.png
[3] http://peterodding.com/code/vim/session/#sample_session_script
[4] http://peterodding.com/code/vim/downloads/session.zip
[5] http://peterodding.com/code/vim/downloads/misc.zip
[6] http://www.vim.org/scripts/script.php?script_id=2332
[7] https://github.com/gmarik/vundle
[8] http://github.com/xolox/vim-session
[9] http://github.com/xolox/vim-misc
[10] http://peterodding.com/code/vim/reload/
[11] http://www.vim.org/scripts/script.php?script_id=42
[12] http://www.vim.org/scripts/script.php?script_id=2771
[13] http://www.vim.org/scripts/script.php?script_id=1658
[14] http://www.vim.org/scripts/script.php?script_id=69
[15] http://www.vim.org/scripts/script.php?script_id=273
[16] http://peterodding.com/code/vim/shell/
[17] http://peterodding.com/code/vim/session
[18] http://peterodding.com/code/vim/shell
[19] http://www.vim.org/scripts/script.php?script_id=3150
[20] http://en.wikipedia.org/wiki/MIT_License
vim: ft=help