zeroknight / vim-signjump

Jump to signs just like other object motions. A feature that is oddly absent from Vim.

vim-signjump

Jump to signs just like other object motions. A feature that is oddly absent from Vim.

Jump Around

Most plugins that make use of the sign column supply mappings or commands that jump to their respective signs. This plugin aims to provide the same behavior as a generic motion that works in any file with signs.

Usage

Using SignJump is simple. By default, the plugin defines mappings for jumping to the next, previous, first or last sign with mappings akin to Tim Pope's Unimpaired plugin. Use ]s to jump to the next sign, and [s to jump to the previous sign. An optional count can be given to jump n signs at a time. Likewise, capital S variants jump to the first and last signs in the buffer.

Jumps are relative to the cursor position. If there is no sign in the jump direction, or no signs in the current buffer at all, the cursor will not move.

In addition, there are supplementary commands that offer the same functionality. See :h signjump-commands for details.

Installation

No special steps are required for installation. Refer to your plugin manager's documentation for detailed and specific setup and plugin installation instructions. Or, if you prefer to do things the hard way, you can manually install SignJump by adding its directories to your ~/.vim directory.

Using Vim-Plug or Vundle

Using Vim-Plug:

Plug 'ZeroKnight/vim-signjump'

Run :PlugInstall in Vim.

Using Vundle:

Plugin 'ZeroKnight/vim-signjump'

Run :PluginInstall in Vim.

Using Pathogen

cd ~/.vim/bundle
git clone git://github.com/ZeroKnight/vim-signjump.git

Run :Helptags in Vim.

Using Vim or Neovim packages

Vim, as of version 7.4.1486, and Neovim have native package management that doesn't require any third-party plugins.

The default package path depends on whether you are using Vim or Neovim, so be sure to use the appropriate path. You may need to create it first, if it does not exist.

cd ~/.vim                    # Vim 8.0
cd ~/.local/share/nvim/site  # Neovim

Create the package directory. (Neo)Vim will look for packages under the 'pack' directory. Each package can contain one or more plugins. Here, we assume you'll put your plugins installed via git in a package called 'git-plugins', but you can name this whatever you'd like.

mkdir -p pack/git-plugins/start

Clone the repository.

git clone https://github.com/ZeroKnight/vim-signjump pack/git-plugins/start/vim-signjump

You'll need to generate tags for the help file in order to view it with :help. You can do this manually, or add the following to the end of your vimrc/init.vim:

" Load packages now so that they are in 'runtimepath', otherwise helptags won't
" be able to find them.
packloadall

" Quietly generate tags for help files.
silent! helptags ALL

Configuration

See :h signjump-configuration for options.

Background

SignJump is my first Vim plugin. I was inspired to write it by this Vi & Vim Stack Exchange question.

I thought that it was very peculiar that Vim doesn't have a user-friendly way to jump to signs. The closest thing would be :sign jump ..., but having to supply a specific ID and buffer/file name is hardly user-friendly, and there's no mapping equivalent.

I hope that you find this plugin useful, and appreciate its simplicity and light weight. I wrote this plugin with the vision that it be one of those "must have missing features" type plugins that anyone would want in their Vim configuration.

Acknowledgements

• Andreas Louv - Early code review.
• Luc Hermitte - Insightful early code review and suggestions; drove several refactors. Answered my neophyte questions. Thank you!

vim-signjump's Issues

Turn contiguous regions of signs with the same name into text objects

Would also be good to treat groups of signs as the same sign type

This might be tricky if there are overlapping regions with different signs. Maybe able to do text object by specific sign names, or set the priorities of the different names

Address conflict with default spell-check mappings

By default, (Neo)Vim uses [s, [S, ]s, and ]S for jumping to words highlighted by the spell-check system. This should be addressed in some way. Some ideas:

• Different choice in mappings, perhaps substitute brackets [|] for angle brackets <|>
  • Alternatively, an option that automatically maps the spell-check mappings to the angle bracket variants
• Different letter choice, perhaps ]j, ]J, ]k, ]K? Not quite as intuitive due to how overloaded and ambiguous bare j and k are as a concept.
• Default to <Leader> mappings
  • <Leader>sj/<Leader>sJ for next/last sign and <Leader>sk/<Leader>sK for prev/first sign?

Working out of the box is an important design choice, so there should be no user requirement to map or remap anything themselves, so unbound by default or any kind of prompt is out of the question.

Finalize interface for name-filtered jump mappings and update help

Regarding #8:

• Settle on a final interface for user-creation of name-filtered jump mappings
• Add usage info and examples to help file.

Plugin expects a english locale

Hi,
this plugin parses the output of the :sign command. However it only works, if it is run in an english locale (e.g. try running :lang mes de_DE and it will fail miserably :()
So please consider for parsing switching the locale to english. I am doing something similar for my DynamicsSign plugin here

Add unit tests

• See how other plugin others implement unit tests
• Implement a few for this plugin

Use `sign_getplaced` instead of `:sign place` when possible.

There's a new signs API (available in Vim 8.1.0772 and in Neovim), it doesn't need text parsing to get at the juicy bits, unlike :signs place list.

Of course, wholesale moving to this easier-to-use API does mean the plugin wouldn't be compatible with older versions o (Neo)Vim anymore. Another option is conditional usage, though that likely only has the disadvantage of quasi-duplicating code.

I'm unsure whether it has performance benefits.

Usage of it in vim-lsp:

$ rg 'sign_[a-z_]*\('
autoload/lsp/ui/vim/signs.vim
55:    call sign_define(a:sign_name, l:options)
78:    call sign_undefine('LspError')
79:    call sign_undefine('LspWarning')
80:    call sign_undefine('LspInformation')
81:    call sign_undefine('LspHint')
104:    let l:sign_group = s:get_sign_group(a:server_name)
105:    call sign_unplace(l:sign_group, { 'buffer': a:path })
108:function! s:get_sign_group(server_name) abort
115:    let l:sign_group = s:get_sign_group(a:server_name)
125:                let l:sign_id = sign_place(0, l:sign_group, l:sign_name, a:path, { 'lnum': l:line })
   vim

Sign caching is imperfect

The current method of relying on an autocmd to refresh the buffer's cache (b:signjump_signs) of signs is flawed. While the current list of events to trigger on covers a lot of cases, there are still edge cases that cannot be easily covered.

For example, this scenario with GitGutter:

1. Be in normal mode long enough that CursorHold is triggered. This causes a refresh of the buffer's sign cache.
2. Disable GitGutter with :GitGutterDisable or :GitGutterToggle. GitGutter's signs disappear, but the sign cache is not updated to reflect this.
3. Try to jump to the next/previous sign. Vim will throw an error for trying to jump to a non-existent sign because the cache is stale.

Possible Solutions

1. Ditch the autocmd and simply build the sign list on each jump.
   • I worry that this will see performance hits on buffers with a great enough number of signs. Is this something that could occur outside of rare occasions, though?
2. On top of the existing autocmd events, add a global timer that periodically refreshes the cache in the background.
   • This is obviously prone to race conditions and would likely be doing unnecessary work most of the time.
3. Ask Bram to include an autocmd event for changes to signs
   • This would be the most ideal possible solution

Add ability to jump in Visual mode

Jumping to signs while in Visual mode would be pretty useful, especially Visual-Line mode.

Jump through contiguous regions

If I have multiple lines in a row with a sign I would like to be able to jump to the next section of lines with a sign in it and skip over all the remaining ones in the section I am in

Ideally signs could be configurably grouped (e.g. all signs from a certain plugin) and those treated as a single section

Jump by sign names

It would be nice to be able to set up a mapping something like

nnoremap ]d signjump#next_sign(123, 234)

which would only jump to signs 123 and 234 instead of all signs

Support 'wrapscan'

Should NextSign and PrevSign support 'wrapscan' behavior?

In essence, much like searching, NextSign on or after the last sign would wrap to the beginning of the file and end up on the first sign, vice-versa for PrevSign.

Remember to update the README to reflect this change.

Jumping with no valid signs moves cursor to the beginning of the line

Regression with the latest few commits leading up to 6ccc076.

See also #8

Improve install instructions

Plugin installation is pretty straightforward, but some basic steps are good to have, especially for those new to Vim.

Get signs from all groups

Currently vim-signjump uses the following to get a list of all placed signs in a buffer:

split(execute('sign place buffer='.a:buffer, 'silent'), '\n'), 

However, this doesn't work when a plugin has placed signs in their own group (an example is vim-lsp).

Changing this to:

split(execute('sign place group=* buffer='.a:buffer, 'silent'), '\n'), 

Fixes it. I haven't been able to observe an ill effect in vim-signjump.