Commit 52cffe75 authored by Tim Allen's avatar Tim Allen

Add separate docs for the new custom commands.

parent 41a8570b
......@@ -64,20 +64,7 @@ Installation
git clone https://gitlab.com/Screwtapello/kakoune-state-save.git
4. If you want to save and restore command history, search history,
or other registers, put a fragment like this into your `kakrc`
(see `:doc registers` for register names):
hook global KakBegin .* %{
state-save-reg-sync colon
state-save-reg-sync pipe
state-save-reg-sync slash
}
hook global KakEnd .* %{
state-save-reg-sync colon
state-save-reg-sync pipe
state-save-reg-sync slash
}
or other registers, see the "Commands" and "Usage" sections below.
Configuration
=============
......@@ -112,34 +99,105 @@ whose content often changes,
like the temporary files used for commit messages
or for bash's `fc` command.
Commands
========
Different people use Kakoune's registers in different ways,
so instead of providing a bunch of configuration options,
this plugin provides the following commands
you can call from your own hooks or mappings:
`state-save-reg-save <regname>`
-------------------------------
**regname:** One of the alphabetic register names
from Kakoune's `:doc registers` documentation.
Saves the current contents of the named register
to a file in the `%opt{state_save_path}` directory.
`state-save-reg-load <regname>`
-------------------------------
**regname:** One of the alphabetic register names
from Kakoune's `:doc registers` documentation.
Loads the current contents of the named register
from a file in the `%opt{state_save_path}` directory.
**Note:** Different Kakoune registers behave differently
when loading new values.
For most registers, the new values entirely replace the old values.
For history-like registers
(such as `colon`, the command-history register,
and `slash`, the search-history register)
the new values are appended, and then duplicates are removed.
**WARNING:** Properly loading register contents
requires using Kakoune's `evaluate-commands` feature,
which means anyone who can write to files in `%opt{state_save_path}`
can make your Kakoune _**execute arbitrary code**_
when you invoke `state-save-reg-load`.
`state-save-reg-sync <regname>`
-------------------------------
**regname:** One of the alphabetic register names
from Kakoune's `:doc registers` documentation.
Invoking `state-save-reg-sync whatever` is exactly the same as:
state-save-reg-load whatever
state-save-reg-save whatever
For history-like registers
(see the note under `state-save-reg-load` above),
this incorporates any items from other Kakoune sessions
into this Kakoune session,
and makes this sessions' items available
to other sessions.
**WARNING:** See the warning under `state-save-reg-load` above.
Usage
=====
After the plugin is installed,
saving and restoring cursor positions works automatically.
If you have added the `KakBegin` and `KakEnd` hooks to your `kakrc`
as described above,
the command-history (the `colon` register),
the shell-command-history (the `pipe` register),
and the search history (the `slash` register)
should all be saved and restored too.
You might also want to save and restore other registers at other times.
To save and restore command-history, search history, and pipe-command history,
add a snippet like this to your `kakrc` file:
hook global KakBegin .* %{
state-save-reg-sync colon
state-save-reg-sync pipe
state-save-reg-sync slash
}
hook global KakEnd .* %{
state-save-reg-sync colon
state-save-reg-sync pipe
state-save-reg-sync slash
}
You can save and restore other registers too,
see `:doc registers` to learn more.
**WARNING:** `state-save-reg-load` (and therefore `state-save-reg-sync`)
has security implications;
see the warning in the `state-save-reg-load` section above.
Alternatively,
if you might want to sync registers more frequently
(in case Kakoune crashes,
or to keep multiple Kakoune sessions in sync)
you could run those commands from some other hook, like `NormalIdle`,
`FocusOut` or `FocusIn`.
For example,
if you save the `dquote` register in a `FocusOut` hook,
and load it in a `FocusIn` hook,
you can copy/paste between Kakoune sessions.
**NOTE:** Kakoune stores marks with
the `%val{bufname}` of the buffer they were stored with.
This name is only valid within a single session,
so it doesn't make sense to save or restore registers used to store marks.
**WARNING:** Loading registers involves
passing the stored register contents to `eval`,
so do not use this feature if you do not trust
everybody with write-access to the `%opt{state_save_path}` directory.
I keep my yank/paste buffer synchronised between Kakoune sessions like this:
hook global FocusOut .* %{ state-save-reg-save dquote }
hook global FocusIn .* %{ state-save-reg-load dquote }
TODO
====
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment