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: 10 days ago
JSON representation

Manges git branch specific vim session files

Lists

README 

        
# ticket.vim



Vim session management system with a focus on git branches.



![manual-ticket-gif](https://user-images.githubusercontent.com/16519378/197326413-539badb9-e93f-49ad-a829-2c3d09e1f09d.gif)



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



![session-save-auto](https://user-images.githubusercontent.com/16519378/195995769-e3323079-c5f3-415e-9ed5-a582a9174625.gif)



Find and open sessions using FZF:



![fzf-session](https://user-images.githubusercontent.com/16519378/195995818-597233ee-b32e-4063-8a42-86d23fc86b79.gif)



Save and open notes associated with a branch/session:



![note-save-open](https://user-images.githubusercontent.com/16519378/195995824-bcfc1a5d-51ff-46a0-8976-27ef07bb1fd1.gif)



Grepping note file contents and opening them using FZF:



![fzf-notes](https://user-images.githubusercontent.com/16519378/195995834-b8101bf5-4929-4cdc-8cc1-5faf557e5712.gif)



## 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/`.