Vim provides a native tool to save your time, helping you to get back to the previous mindset of the last time you left the project. It’s called sessions.
(from :help sessions…)
A Session keeps the Views for all windows, plus the global settings. You can save a Session and when you restore it later the window layout looks the same. You can use a Session to quickly switch between different projects, automatically loading the files you were last working on in that project.
Vim’s sessions is basically a tool to instantly save the state of everything in your current Vim session, allowing you to restore it the next time, instead of opening from scratch all the tabs/windows/buffers again.
In this post, we’ll start by taking a look at the commands used to deal with sessions, and then, check some use cases for different workflows.
After that, we’ll bring some attention to whether or not session files should be committed to the project’s git repository. Lastly, we’ll create a bonus custom command to help quickly save the session, save modified files, and exit Vim with class, all at once!
Understanding the Commands:
To Save a Session (:mksession, :mks)
The :mksession command, or :mks, is responsible for saving the current session. What the command actually does is that it writes a Vim script file that restores the current session.
If used alone, :mks will create a Session.vim file on the directory where the current Vim execution was started.
Using exclamation mark, :mks! the command overwrites Session.vim file if it exists in the directory.
You can specify a custom file name to save the session :mks! my-session.vim. This allows you to save different sessions that can be used to work on different parts of the same project, for example, backend-api.vim, frontend.vim, devops.vim.
(You may consider creating a vim-sessions/ folder inside your project’s root directory if the number of session files for the project keeps growing).
To Restore a Session (:source, :so, vim -S)
There are basically two ways to restore a Vim session:
- On the terminal, before starting Vim, with the vim -S option:
(Assuming your pwd on the terminal is the project’s root directory).
If your project already has a session autogenerated file (Session.vim), you can start Vim with the command vim -S, and it will look for the Sessions.vim file and start the session.
If you need to start from a custom session file, you might provide the file name with the command, example: vim -S my-session.vim.
- Inside vim, using the :source or :so command:
If Vim is already running and you want to restore a session, you can use the command :source (:so) to restore a session, for example, :so my-session.vim.
It is very useful for projects that have many custom session files, allowing the user to change sessions without exiting Vim.
Example Use Cases:
Daily Saving Sessions of an Ongoing Project
While working on an ongoing project, it’s possible that your Vim screen has many windows and/or tabs opened, and it helps a lot to be able to save the state before stop working, to be able to open it next day at the same state.
The tabs/windows that you’re working on today, possibly may not be the same that you’ll be working 3 days after. Maybe the file structure of the project isn’t the same 3 days after, and one file or another has been removed. Your project is still changing a lot.
What matters to you, in this case, is only getting back tomorrow, from where you left today.
- Saving the session:
For this daily use case, you can simply use the command :mks! Before exiting Vim.
- Restoring the session:
The next day at the terminal, at the project’s root folder, just type vim -S and you’re back where you left.
Mantaining Stable Projects
Another use case is when you need to do some maintenance on specific parts of a stable project. Maybe you just want to change prices for your product’s site and highlight the price with some custom CSS.
Maybe you just need to get to those 2 files, at those specific lines where the price change and the CSS change will happen. You don’t touch the project for a while and you don’t remember exactly where things were, or maybe you just asked your co-worker to do this change as you’re busy with another thing.
It would be great to open only the needed files at the exact lines, right?
- Saving the session:
Just get the session to the state needed, related files opened, cursor positioned on the correct lines, and save it with a custom session name with: :mks! price-update.vim.
- Restoring the session:
The next time anyone needs to make price updates, from the project’s folder on the terminal, start Vim with: vim -S price-update.vim
- Switching sessions:
Let’s say you need to change prices, and also, you remembered to fix that typo on the Purchase Confirmation Message generated on the backend API. Let’s assume you have a backend maintenance session file saved, named backend-api.vim.
After finishing the price changes, you simply switch sessions with the :source command: :so backend-api.vim.
Extras:
To git or Not To git?
Should you commit the session files created, to your project’s repository? If the project will be touched by more than one person, that’s something to be discussed with the other part(s).
My suggestion on that, based on the 2 workflows presented before, is:
- Add
Sessions.vimto your project’s.gitignorefile. - Since this auto-created file is now more related to your personal workflow on the project, it could bring more pain than help if committed to the project’s repo. - Commit
PriceUpdate.vim(example) to the project’s repository.- If you create a custom session file to help quick maintenance on a stable project, it may be worth sharing with others since it could help anyone to dive in and make specific work without searching for files and content inside the project.
An Alias to Save the Session, the Modified Files, and Exit
You may know the difference of :wq! or :x to save and exit Vim, that’s not the point here, I’ll stick with :x but you can easily change the following tip the way you prefer.
Add the following code to your .vimrc file:
command! Xs :mks! | :xa "save the session, save modified files, and exit
The next time you exit your project, make sure you do it with class👌 using :Xs!
Useful links & references:
- Vim Documentation (
:help) - There’s a different workflow for Vim
sessionson this post: Simple Vim session management: Part 1. - There are a few plugins to extend
sessionscapabilities, like tpope/vim-obsession and xolox/vim-session. - “Mastering Vim Quickly” Book (and screencasts) by Jovica Ilic. It’s an awesome book, make sure you subscribe to the newsletter to get free Vim tips and book excerpts on your email.
(👆 This is an affiliate link. If you got any value from this post and are also interested in buying the MVQ book/screencasts, please consider visiting the affiliate link and you’ll be gifting me a coffee ☕ or a beer 🍺.)
Footnotes:
Follow me on Twitter to get more posts like this and other quick tips in your feed.
alldrops.info is the TRUE and FOREVER FREE home for the previously used medium.com/vim-drops publication. At alldrops.info you’ll always find all posts without Medium.com restrictions.
If you have any doubts or tips about this article, I’d appreciate knowing and discussing it via email.
Do you have any other Vim tips? Would you like to publish that in this blog? Please send an email to vim drops.
As English is not my native language, I apologize for the errors. Corrections are welcome.
Contact: vim [@] alldrops [.] info.
Big thanks 🙌 to Jovica for reviewing this post!
