/
session.txt
363 lines (300 loc) · 15.1 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
*session.txt* Extended session management for Vim
The 'session.vim' 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'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:
Screenshot of auto-save prompt, see reference [1]
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:
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 'session.vim' look like see the sample below
[3].
===============================================================================
*session-installation*
Installation ~
Unzip the most recent ZIP archive [4] file 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). After you restart Vim the following
commands will be available to you:
===============================================================================
*session-commands*
Commands ~
-------------------------------------------------------------------------------
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 name 'default'
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.
As mentioned earlier your session script will be saved in the directory
pointed to by |g:session_directory|.
-------------------------------------------------------------------------------
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 [5].
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 'session.vim' plug-in.
===============================================================================
*session-options*
Options ~
-------------------------------------------------------------------------------
The *sessionoptions* setting
Because the 'session.vim' 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
-------------------------------------------------------------------------------
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_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_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:loaded_session* option
This variable isn't really an option but if you want to avoid loading the
'session.vim' 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 fully compatible with plug-ins that create
buffers with generated content and because of this 'session.vim' includes
specific workarounds for such plug-ins:
- NERD tree [6] and Project [7] windows are supported;
- When shell.vim [8] is installed Vim's full-screen state is persisted;
- The netrw (see |netrw-start|) and taglist.vim [9] plug-ins support sessions
out of the box.
If your favorite plug-in doesn't work with 'session.vim' 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-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 [10].
===============================================================================
*session-license*
License ~
This software is licensed under the MIT license [11]. Copyright 2010 Peter
Odding <peter@peterodding.com>.
===============================================================================
*sample-session-script*
Sample session script ~
Here's an example session script generated by the 'session.vim' 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/reload/
[6] http://www.vim.org/scripts/script.php?script_id=1658
[7] http://www.vim.org/scripts/script.php?script_id=69
[8] http://peterodding.com/code/vim/shell/
[9] http://www.vim.org/scripts/script.php?script_id=273
[10] http://www.vim.org/scripts/script.php?script_id=3150
[11] http://en.wikipedia.org/wiki/MIT_License
vim: ft=help