auto-save.nvim/doc/auto-save.nvim.txt

*auto-save.nvim.txt*     For Neovim >= 0.8.0     Last change: 2024 December 04

==============================================================================
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
    - 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",
      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                          *auto-save.nvim-installation-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                                *auto-save.nvim-installation-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
<


==============================================================================
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)
      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                   *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 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.


==============================================================================
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", "<cmd>ASToggle<CR>", {})
<

or as part of the `lazy.nvim` plugin spec:

>lua
    {
      "okuuva/auto-save.nvim",
      keys = {
        { "<leader>n", "<cmd>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 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.


==============================================================================
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: