mirror of
https://github.com/zoriya/auto-save.nvim.git
synced 2025-12-06 06:36:11 +00:00
270 lines
9.1 KiB
Plaintext
270 lines
9.1 KiB
Plaintext
*auto-save.nvim.txt* For Neovim >= 0.8.0 Last change: 2024 February 27
|
||
|
||
==============================================================================
|
||
Table of Contents *auto-save.nvim-table-of-contents*
|
||
|
||
1. Features |auto-save.nvim-features|
|
||
2. Requirements |auto-save.nvim-requirements|
|
||
3. Installation |auto-save.nvim-installation|
|
||
- Lazy.nvim |auto-save.nvim-installation-lazy.nvim|
|
||
- Packer.nvim |auto-save.nvim-installation-packer.nvim|
|
||
- vim-plug |auto-save.nvim-installation-vim-plug|
|
||
4. Configuration |auto-save.nvim-configuration|
|
||
- Trigger Events |auto-save.nvim-configuration-trigger-events|
|
||
- Condition |auto-save.nvim-configuration-condition|
|
||
5. Usage |auto-save.nvim-usage|
|
||
6. Events / Callbacks |auto-save.nvim-events-/-callbacks|
|
||
7. Contributing |auto-save.nvim-contributing|
|
||
8. Acknowledgements |auto-save.nvim-acknowledgements|
|
||
|
||
==============================================================================
|
||
1. Features *auto-save.nvim-features*
|
||
|
||
- automatically save your changes so the world doesn’t collapse
|
||
- highly customizable:
|
||
- conditionals to assert whether to save or not
|
||
- execution message (it can be dimmed and personalized)
|
||
- events that trigger auto-save
|
||
- debounce the save with a delay
|
||
- hook into the lifecycle with autocommands
|
||
- automatically clean the message area
|
||
|
||
|
||
==============================================================================
|
||
2. Requirements *auto-save.nvim-requirements*
|
||
|
||
- Neovim >= 0.8.0
|
||
|
||
|
||
==============================================================================
|
||
3. Installation *auto-save.nvim-installation*
|
||
|
||
Install the plugin with your favourite package manager:
|
||
|
||
|
||
LAZY.NVIM *auto-save.nvim-installation-lazy.nvim*
|
||
|
||
>lua
|
||
{
|
||
"okuuva/auto-save.nvim",
|
||
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 *auto-save.nvim-installation-packer.nvim*
|
||
|
||
>lua
|
||
use({
|
||
"okuuva/auto-save.nvim",
|
||
config = function()
|
||
require("auto-save").setup {
|
||
-- your config goes here
|
||
-- or just leave it empty :)
|
||
}
|
||
end,
|
||
})
|
||
<
|
||
|
||
|
||
VIM-PLUG *auto-save.nvim-installation-vim-plug*
|
||
|
||
>vim
|
||
Plug 'okuuva/auto-save.nvim'
|
||
lua << EOF
|
||
require("auto-save").setup {
|
||
-- your config goes here
|
||
-- or just leave it empty :)
|
||
}
|
||
EOF
|
||
<
|
||
|
||
|
||
==============================================================================
|
||
4. Configuration *auto-save.nvim-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)
|
||
execution_message = {
|
||
enabled = true,
|
||
message = function() -- message to print on save
|
||
return ("AutoSave: saved at " .. vim.fn.strftime("%H:%M:%S"))
|
||
end,
|
||
dim = 0.18, -- dim the color of `message`
|
||
cleaning_interval = 1250, -- (milliseconds) automatically clean MsgArea after displaying `message`. See :h MsgArea
|
||
},
|
||
trigger_events = { -- See :h events
|
||
immediate_save = { "BufLeave", "FocusLost" }, -- vim events that trigger an immediate save
|
||
defer_save = { "InsertLeave", "TextChanged" }, -- vim events that trigger a deferred save (saves after `debounce_delay`)
|
||
cancel_defered_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
|
||
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 *auto-save.nvim-configuration-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 *auto-save.nvim-configuration-condition*
|
||
|
||
The `condition` field of the configuration allows the user to exclude
|
||
**auto-save** from saving specific buffers.
|
||
|
||
Here is an example using a helper function from `auto-save.utils.data` that
|
||
disables auto-save for specified file types:
|
||
|
||
>lua
|
||
{
|
||
condition = function(buf)
|
||
local fn = vim.fn
|
||
local utils = require("auto-save.utils.data")
|
||
|
||
-- don't save for `sql` file types
|
||
if utils.not_in(fn.getbufvar(buf, "&filetype"), {'sql'}) then
|
||
return true
|
||
end
|
||
return false
|
||
end
|
||
}
|
||
<
|
||
|
||
You may also exclude `special-buffers` see (`:h buftype` and `:h
|
||
special-buffers`):
|
||
|
||
>lua
|
||
{
|
||
condition = function(buf)
|
||
local fn = vim.fn
|
||
|
||
-- don't save for special-buffers
|
||
if fn.getbufvar(buf, "&buftype") ~= '' then
|
||
return false
|
||
end
|
||
return true
|
||
end
|
||
}
|
||
<
|
||
|
||
Buffers that are `nomodifiable` are not saved by default.
|
||
|
||
|
||
==============================================================================
|
||
5. Usage *auto-save.nvim-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", "<leader>n", ":ASToggle<CR>", {})
|
||
<
|
||
|
||
or as part of the `lazy.nvim` plugin spec:
|
||
|
||
>lua
|
||
{
|
||
"okuuva/auto-save.nvim",
|
||
keys = {
|
||
{ "<leader>n", ":ASToggle<CR>", desc = "Toggle auto-save" },
|
||
},
|
||
...
|
||
},
|
||
<
|
||
|
||
|
||
==============================================================================
|
||
6. Events / Callbacks *auto-save.nvim-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 always print the file name before a file is getting saved (use
|
||
`:messages` if the execution message swallows the print):
|
||
|
||
>lua
|
||
local group = vim.api.nvim_create_augroup('autosave', {})
|
||
|
||
vim.api.nvim_create_autocmd('User', {
|
||
pattern = 'AutoSaveWritePre',
|
||
group = group,
|
||
callback = function(opts)
|
||
if opts.data.saved_buffer ~= nil then
|
||
local filename = vim.api.nvim_buf_get_name(opts.data.saved_buffer)
|
||
print('We are about to save ' .. filename .. ' get ready captain!')
|
||
end
|
||
end,
|
||
})
|
||
<
|
||
|
||
If you want more Events, feel free to open an issue.
|
||
|
||
|
||
==============================================================================
|
||
7. Contributing *auto-save.nvim-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.
|
||
|
||
|
||
==============================================================================
|
||
8. Acknowledgements *auto-save.nvim-acknowledgements*
|
||
|
||
This plugin wouldn’t exist without Pocco81 <https://github.com/Pocco81>’s
|
||
work on the original <https://github.com/Pocco81/auto-save.nvim>.
|
||
|
||
==============================================================================
|
||
9. Links *auto-save.nvim-links*
|
||
|
||
1. *@commitlint/config-conventional*:
|
||
|
||
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
|
||
|
||
vim:tw=78:ts=8:noet:ft=help:norl:
|