๐งถ auto-save.nvim
auto-save.nvim is a lua plugin for automatically saving your changed buffers in Neovim
Forked from auto-save.nvim as active development has stopped
## ๐ Features
- automatically save your changes so the world doesn't collapse
- highly customizable:
- conditionals to assert whether to save or not
- events that trigger auto-save
- debounce the save with a delay
- hook into the lifecycle with autocommands
- automatically clean the message area
## ๐ Requirements
- Neovim >= 0.8.0
## ๐ฆ Installation
Install the plugin with your favourite package manager:
### [Lazy.nvim]("https://github.com/folke/lazy.nvim")
```lua
{
"okuuva/auto-save.nvim",
version = '^1.0.0', -- see https://devhints.io/semver, alternatively use '*' to use the latest tagged release
cmd = "ASToggle", -- optional for lazy loading on command
event = { "InsertLeave", "TextChanged" }, -- optional for lazy loading on trigger events
opts = {
-- your config goes here
-- or just leave it empty :)
},
},
```
### [Packer.nvim]("https://github.com/wbthomason/packer.nvim")
```lua
use({
"okuuva/auto-save.nvim",
tag = 'v1*',
config = function()
require("auto-save").setup({
-- your config goes here
-- or just leave it empty :)
})
end,
})
```
### [vim-plug]("https://github.com/junegunn/vim-plug")
```vim
Plug 'okuuva/auto-save.nvim', { 'tag': 'v1*' }
lua << EOF
require("auto-save").setup({
-- your config goes here
-- or just leave it empty :)
})
EOF
```
## โ๏ธ Configuration
**auto-save** comes with the following defaults:
```lua
{
enabled = true, -- start auto-save when the plugin is loaded (i.e. when your package manager loads it)
trigger_events = { -- See :h events
immediate_save = { "BufLeave", "FocusLost", "QuitPre", "VimSuspend" }, -- vim events that trigger an immediate save
defer_save = { "InsertLeave", "TextChanged" }, -- vim events that trigger a deferred save (saves after `debounce_delay`)
cancel_deferred_save = { "InsertEnter" }, -- vim events that cancel a pending deferred save
},
-- function that takes the buffer handle and determines whether to save the current buffer or not
-- return true: if buffer is ok to be saved
-- return false: if it's not ok to be saved
-- if set to `nil` then no specific condition is applied
condition = nil,
write_all_buffers = false, -- write all buffers when the current one meets `condition`
noautocmd = false, -- do not execute autocmds when saving
lockmarks = false, -- lock marks when saving, see `:h lockmarks` for more details
debounce_delay = 1000, -- delay after which a pending save is executed
-- log debug messages to 'auto-save.log' file in neovim cache directory, set to `true` to enable
debug = false,
}
```
### Trigger Events
The `trigger_events` field of the configuration allows the user to customize at which events **auto-save** saves.
While the default are very sane and should be enough for most usecases, finetuning for extended possibilities is supported.
It is also possible to pass a pattern to a trigger event, if you only want to execute the event on special file patterns:
``` lua
{
trigger_events = {
immediate_save = {
{ "BufLeave", pattern = { "*.c", "*.h" } }
}
}
}
```
### Condition
The `condition` field of the configuration allows the user to exclude **auto-save** from saving specific buffers.
Here is an example that disables auto-save for specified file types:
```lua
{
condition = function(buf)
local filetype = vim.fn.getbufvar(buf, "&filetype")
-- don't save for `sql` file types
if vim.list_contains({ "sql" }, filetype) then
return false
end
return true
end
}
```
You may also exclude `special-buffers` see (`:h buftype` and `:h special-buffers`):
```lua
{
condition = function(buf)
-- don't save for special-buffers
if vim.fn.getbufvar(buf, "&buftype") ~= '' then
return false
end
return true
end
}
```
Buffers that are `nomodifiable` are not saved by default.
## ๐ Usage
Besides running auto-save at startup (if you have `enabled = true` in your config), you may as well:
- `ASToggle`: toggle auto-save
You may want to set up a key mapping for toggling:
```lua
vim.api.nvim_set_keymap("n", "n", "ASToggle", {})
```
or as part of the `lazy.nvim` plugin spec:
```lua
{
"okuuva/auto-save.nvim",
keys = {
{ "n", "ASToggle", desc = "Toggle auto-save" },
},
...
},
```
## โฉ๏ธ Events / Callbacks
The plugin fires events at various points during its lifecycle which users can hook into:
- `AutoSaveWritePre` Just before a buffer is getting saved
- `AutoSaveWritePost` Just after a buffer is getting saved
- `AutoSaveEnable` Just after enabling the plugin
- `AutoSaveDisable` Just after disabling the plugin
It will always supply the current buffer in the `data.saved_buffer`
An example to print a message with the file name after a file got saved:
```lua
local group = vim.api.nvim_create_augroup('autosave', {})
vim.api.nvim_create_autocmd('User', {
pattern = 'AutoSaveWritePost',
group = group,
callback = function(opts)
if opts.data.saved_buffer ~= nil then
local filename = vim.api.nvim_buf_get_name(opts.data.saved_buffer)
vim.notify('AutoSave: saved ' .. filename .. ' at ' .. vim.fn.strftime('%H:%M:%S'), vim.log.levels.INFO)
end
end,
})
```
Another example to print a message when enabling/disabling autosave:
```lua
local group = vim.api.nvim_create_augroup('autosave', {})
vim.api.nvim_create_autocmd('User', {
pattern = 'AutoSaveEnable',
group = group,
callback = function(opts)
vim.notify('AutoSave enabled', vim.log.levels.INFO)
end,
})
vim.api.nvim_create_autocmd('User', {
pattern = 'AutoSaveDisable',
group = group,
callback = function(opts)
vim.notify('AutoSave disabled', vim.log.levels.INFO)
end,
})
```
If you want more Events, feel free to open an issue.
## ๐ค Contributing
- All pull requests are welcome.
- If you encounter bugs please open an issue.
- Please use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) when commiting.
- See [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional) for more details.
## ๐ Acknowledgements
This plugin wouldn't exist without [Pocco81](https://github.com/Pocco81)'s work on the [original](https://github.com/Pocco81/auto-save.nvim).