Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/superDross/ticket.vim
Manges git branch specific vim session files
https://github.com/superDross/ticket.vim
note-taking plugin vim vim-session
Last synced: 3 months ago
JSON representation
Manges git branch specific vim session files
- Host: GitHub
- URL: https://github.com/superDross/ticket.vim
- Owner: superDross
- License: gpl-3.0
- Created: 2019-08-06T16:09:15.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-15T12:04:39.000Z (10 months ago)
- Last Synced: 2024-06-18T10:33:39.361Z (5 months ago)
- Topics: note-taking, plugin, vim, vim-session
- Language: Vim Script
- Homepage:
- Size: 1.51 MB
- Stars: 16
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ticket.vim
Vim session management system with a focus on git branches.
## Usage
For in vim docs, execute the following command:
```vim
:help ticket.vim
```
### Within a Git Repo
Executing `:SaveSession` will save a session associated with the current branch checked out within the repo.
Executing `:OpenSession` will open the session you saved that is associated with the current branch name.
If you switch branch you can save/open a different session associated with the branch you just switched to without affecting other branch sessions.
`:SaveNote` and `:OpenNote` will save/open notes associated with the branch session.
### Outside a Git Repo
Saving and opening sessions will work and automatically name the session file `main.vim` in case the directory is ever initialised as a git repo.
## Commands
### Sessions
- `:SaveSession` -- To create a session
- `:OpenSession` -- Open a session
- `:DeleteSession` -- Delete the session associated with the current git repo or directory
- `:CleanupSessions` -- Remove sessions that do not have a local branch (only works within git repositories)
- `:ForceCleanupSessions` -- Same as `CleanupSession` but forcefully removes without prompting user (only works within git repositories)
- `:FindSessions *` -- Search all session files name for a given arg and open the quickfix menu (sourcing the sessions under the cursor can be performed by pressing `O`)
- `:TicketSessionsFzf` -- Use fzf to search and open sessions (requires [fzf.vim](https://github.com/junegunn/fzf.vim) or [fzf-lua](https://github.com/ibhagwan/fzf-lua))
### Notes
- `:SaveNote` -- Save notes related to the session
- `:OpenNote` -- Open note associated with the session
- `:DeleteNote` -- Delete the note associated with the current git repo or directory
- `:GrepNotes *` -- Search all notes for given arg
- `:TicketNotesFzf` -- Use fzf to grep and open notes (requires [fzf.vim](https://github.com/junegunn/fzf.vim) or [fzf-lua](https://github.com/ibhagwan/fzf-lua))
## Settings
### Automatic Session Saving/Opening
To automatically open and save session files when opening/closing vim set the following in your `.vimrc`:
```vim
let g:auto_ticket = 1
```
To automatically open session files when **only** opening vim set the following in your `.vimrc`:
```vim
let g:auto_ticket_open = 1
```
To automatically save session files when **only** closing vim set the following in your `.vimrc`:
```vim
let g:auto_ticket_save = 1
```
To **only** allow the auto feature to work in git repo directories set the following in your `.vimrc`:
```vim
let g:auto_ticket_git_only = 1
```
Black list some branches from being used with the auto feature:
```vim
let g:ticket_black_list = ['master', 'other-branch']
```
### Overriding Default Values
Define a default branch name that will used to name all non git repo session files (default: main):
```vim
let g:default_session_name = 'master'
```
Define the directory you want to store all session files within:
```vim
let g:session_directory = '~/my_dir'
```
Use `fzf` instead of vimgrep when executing `:GrepNotes` or `:FindSessions` (default: 0):
```vim
let g:ticket_use_fzf_default = 1
```
Print save/open messages when saving/opening sessions/notes (default: 0):
```vim
let g:ticket_very_verbose = 1
```
Ask for confirmation before overwriting existing session file, will not work if auto save feature are enabled (default: 0):
```vim
let g:ticket_overwrite_confirm = 1
```
## Installation
Requires vim 8.0+ or neovim 0.5+.
With [Vim-Plug](https://github.com/junegunn/vim-plug):
```vim
Plug 'superDross/ticket.vim'
" alternatively pin to specific version (useful if experiencing bugs with a new release)
Plug 'superDross/ticket.vim', { 'tag': '0.10.1' }
```
With [Packer.nvim](https://github.com/wbthomason/packer.nvim):
```lua
require('packer').startup(function(use)
use 'superDross/ticket.vim'
-- alternatively pin to specific version (useful if experiencing bugs with a new release)
use {
'superDross/ticket.vim',
tag = '0.10.1',
}
end)
```
## Demo Features
Automatic saving/opening sessions:
Find and open sessions using FZF:
Save and open notes associated with a branch/session:
Grepping note file contents and opening them using FZF:
## File Storage
The session files are stored as below; git repository directory name with all branch specific session and note files within it.
```
~/.local/share/tickets-vim/
│
└── /
├── .md
└── .vim
```
The legacy root directory is `~/.tickets`, however, if this is not currently being used (or it has not been set via `g:session_directory`) then the [XDG base directory spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) will be followed.
This will check and prioritise the directory set in `$XDG_DATA_HOME`, if not set then `~/.local/share` will be used.
## Limitations
- The organisation and storage of the branch based session files depends upon the repo & git branch pairing name being unique.
- Only works within \*NIX based systems.
- This plugin assumes it has the appropriate permissions for modifying files locally
- All `/` substrings in a branch name will be replaced with `%` as `/` cannot be part of a files name in *NIX based systems
## Developing
When creating fixes/features you can test that your changes do not break any existing features by executing the following make command in the root directory of the project:
```sh
make test
```
## Manual Documentation Generation
Your package manager should take care of generating the documentation, however, if you want to generate them yourself you should execute `:helptags /dir/to/ticket.vim/doc/`.