{"id":13758670,"url":"https://github.com/MattesGroeger/vim-bookmarks","last_synced_at":"2025-05-10T08:30:39.269Z","repository":{"id":15036242,"uuid":"17762124","full_name":"MattesGroeger/vim-bookmarks","owner":"MattesGroeger","description":"Vim bookmark plugin","archived":false,"fork":false,"pushed_at":"2023-12-28T17:12:25.000Z","size":1360,"stargazers_count":959,"open_issues_count":33,"forks_count":98,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-11-16T15:37:45.002Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.vim.org/scripts/script.php?script_id=4893","language":"Vim script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MattesGroeger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-03-14T22:17:39.000Z","updated_at":"2024-11-01T19:38:29.000Z","dependencies_parsed_at":"2024-11-16T15:32:37.696Z","dependency_job_id":"e9923168-adc5-4633-8ed7-e602ecb7ff0b","html_url":"https://github.com/MattesGroeger/vim-bookmarks","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MattesGroeger%2Fvim-bookmarks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MattesGroeger%2Fvim-bookmarks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MattesGroeger%2Fvim-bookmarks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MattesGroeger%2Fvim-bookmarks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MattesGroeger","download_url":"https://codeload.github.com/MattesGroeger/vim-bookmarks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253389472,"owners_count":21900765,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T13:00:34.320Z","updated_at":"2025-05-10T08:30:37.951Z","avatar_url":"https://github.com/MattesGroeger.png","language":"Vim script","funding_links":[],"categories":["Vim Script","Plugins"],"sub_categories":[],"readme":"## vim-bookmarks [![Build Status](https://travis-ci.org/MattesGroeger/vim-bookmarks.svg)](https://travis-ci.org/MattesGroeger/vim-bookmarks) [![Release](http://img.shields.io/github/release/MattesGroeger/vim-bookmarks.svg)](https://github.com/MattesGroeger/vim-bookmarks/releases) [![Release](http://img.shields.io/github/issues/MattesGroeger/vim-bookmarks.svg)](https://github.com/MattesGroeger/vim-bookmarks/issues)\n\nThis vim plugin allows toggling bookmarks per line. A quickfix window gives access to all bookmarks. Annotations can be added as well. These are special bookmarks with a comment attached. They are useful for preparing code reviews. All bookmarks will be restored on the next startup.\n\n![Preview](https://raw.github.com/MattesGroeger/vim-bookmarks/master/preview.gif)\n\n#### Bright Colors Example\n\n[![Screenshot Bright Colors](https://raw.github.com/MattesGroeger/vim-bookmarks/master/screenshot-bright-small.png)](https://raw.github.com/MattesGroeger/vim-bookmarks/master/screenshot-bright.png)\n\n```viml\nhighlight BookmarkSign ctermbg=NONE ctermfg=160\nhighlight BookmarkLine ctermbg=194 ctermfg=NONE\nlet g:bookmark_sign = '♥'\nlet g:bookmark_highlight_lines = 1\n```\n\n### Features\n\n* Toggle bookmarks per line ⚑\n* Add annotations per line ☰\n* Navigate all bookmarks with quickfix window\n* Bookmarks will be restored on next startup\n* [Bookmarks per working directory](https://github.com/MattesGroeger/vim-bookmarks#bookmarks-per-working-directory) (optional)\n* Fully customisable (signs, sign column, highlights, mappings)\n* Integrates with [Unite's](https://github.com/Shougo/unite.vim) quickfix source if installed\n* Integrates with [ctrlp.vim](https://github.com/ctrlpvim/ctrlp.vim) if installed\n* Works independently from [vim marks](http://vim.wikia.com/wiki/Using_marks)\n\n## Installation\n\nBefore installation, please check your Vim supports signs by running `:echo has('signs')`.  `1` means you're all set; `0` means you need to install a Vim with signs support. If you're compiling Vim yourself you need the 'big' or 'huge' feature set. [MacVim][] supports signs.\n\nUse your favorite plugin manager:\n\n* [Pathogen][]\n  * `git clone https://github.com/MattesGroeger/vim-bookmarks.git ~/.vim/bundle/vim-bookmarks`\n* [Vundle][]\n  1. Add `Plugin 'MattesGroeger/vim-bookmarks'` to .vimrc\n  2. Run `:PluginInstall`\n* [NeoBundle][]\n  1. Add `NeoBundle 'MattesGroeger/vim-bookmarks'` to .vimrc\n  2. Run `:NeoBundleInstall`\n* [vim-plug][vimplug]\n  1. Add `Plug 'MattesGroeger/vim-bookmarks'` to .vimrc\n  2. Run `:PlugInstall`\n\n## Usage\n\nAfter installation you can directly start using it. You can do this by either using the default shortcuts or the commands:\n\n| Action                                          | Shortcut    | Command                      |\n|-------------------------------------------------|-------------|------------------------------|\n| Add/remove bookmark at current line             | `mm`        | `:BookmarkToggle`            |\n| Add/edit/remove annotation at current line      | `mi`        | `:BookmarkAnnotate \u003cTEXT\u003e`   |\n| Jump to next bookmark in buffer                 | `mn`        | `:BookmarkNext`              |\n| Jump to previous bookmark in buffer             | `mp`        | `:BookmarkPrev`              |\n| Show all bookmarks (toggle)                     | `ma`        | `:BookmarkShowAll`           |\n| Clear bookmarks in current buffer only          | `mc`        | `:BookmarkClear`             |\n| Clear bookmarks in all buffers                  | `mx`        | `:BookmarkClearAll`          |\n| Move up bookmark at current line                | `[count]mkk`| `:BookmarkMoveUp [\u003cCOUNT\u003e]`  |\n| Move down bookmark at current line              | `[count]mjj`| `:BookmarkMoveDown [\u003cCOUNT\u003e]`|\n| Move bookmark at current line to another line   | `[count]mg` | `:BookmarkMoveToLine \u003cLINE\u003e` |\n| Save all bookmarks to a file                    |             | `:BookmarkSave \u003cFILE_PATH\u003e`  |\n| Load bookmarks from a file                      |             | `:BookmarkLoad \u003cFILE_PATH\u003e`  |\n\nYou can change the shortcuts as you like, just read on...\n\n## Customization\n\n### Key Bindings\n\nYou can overwrite any of the default mappings. Just put the following into your `~/.vimrc` and adjust as you like:\n\n```viml\nnmap \u003cLeader\u003e\u003cLeader\u003e \u003cPlug\u003eBookmarkToggle\nnmap \u003cLeader\u003ei \u003cPlug\u003eBookmarkAnnotate\nnmap \u003cLeader\u003ea \u003cPlug\u003eBookmarkShowAll\nnmap \u003cLeader\u003ej \u003cPlug\u003eBookmarkNext\nnmap \u003cLeader\u003ek \u003cPlug\u003eBookmarkPrev\nnmap \u003cLeader\u003ec \u003cPlug\u003eBookmarkClear\nnmap \u003cLeader\u003ex \u003cPlug\u003eBookmarkClearAll\nnmap \u003cLeader\u003ekk \u003cPlug\u003eBookmarkMoveUp\nnmap \u003cLeader\u003ejj \u003cPlug\u003eBookmarkMoveDown\nnmap \u003cLeader\u003eg \u003cPlug\u003eBookmarkMoveToLine\n```\nYou can disable all default key bindings by setting the following in your `~/.vimrc`:\n\n```viml\nlet g:bookmark_no_default_key_mappings = 1\n```\n\n### Colors\n\nOverwrite the default hightlight groups by adding this to your colorscheme or `.vimrc`:\n\n```viml\nhighlight BookmarkSign ctermbg=whatever ctermfg=whatever\nhighlight BookmarkAnnotationSign ctermbg=whatever ctermfg=whatever\nhighlight BookmarkLine ctermbg=whatever ctermfg=whatever\nhighlight BookmarkAnnotationLine ctermbg=whatever ctermfg=whatever\n```\n\n### Options\n\nPut any of the following options into your `~/.vimrc` in order to overwrite the default behaviour.\n\n| Option                                         | Default                  | Description                                             |\n|------------------------------------------------|--------------------------|---------------------------------------------------------|\n| `let g:bookmark_sign = '\u003e\u003e'`                   | ⚑                        | Sets bookmark icon for sign column                      |\n| `let g:bookmark_annotation_sign = '##'`        | ☰                        | Sets bookmark annotation icon for sign column           |\n| `let g:bookmark_save_per_working_dir = 1`      | 0                        | Save bookmarks per working dir, the folder you opened vim from |\n| `let g:bookmark_auto_save = 0`                 | 1                        | Enables/disables automatic saving for bookmarks         |\n| `let g:bookmark_manage_per_buffer = 1`         | 0                        | Save bookmarks when leaving a buffer, load when entering one |\n| `let g:bookmark_auto_save_file = '/bookmarks'` | $HOME .'/.vim-bookmarks' | Sets file for auto saving (ignored when `bookmark_save_per_working_dir` is enabled) |\n| `let g:bookmark_auto_close = 1`                | 0                        | Automatically close bookmarks split when jumping to a bookmark |\n| `let g:bookmark_highlight_lines = 1`           | 0                        | Enables/disables line highlighting                      |\n| `let g:bookmark_show_warning = 0`              | 1                        | Enables/disables warning when clearing all bookmarks    |\n| `let g:bookmark_show_toggle_warning = 0`       | 1                        | Enables/disables warning when toggling to clear a bookmark with annotation   |\n| `let g:bookmark_center = 1`                    | 0                        | Enables/disables line centering when jumping to bookmark|\n| `let g:bookmark_no_default_key_mappings = 1`                    | 0                        | Prevent any default key mapping from being created|\n| `let g:bookmark_location_list = 1`             | 0                        | Use the location list to show all bookmarks             |\n| `let g:bookmark_disable_ctrlp = 1`             | 0                        | Disable ctrlp interface when  show all bookmarks             |\n| `let g:bookmark_display_annotation = 1`        | 0                        | Display annotation text on the status line              |\n\n### Bookmarks per working directory\n\nThis feature allows the grouping of bookmarks per root directory. This way bookmarks from other projects are not interfering. This is done by saving a file called `.vim-bookmarks` into the current working directory (the folder you opened vim from).\n\nWhenever a vim instance is opened from the same root folder the bookmarks from that folder will be loaded. Note, that you can place your bookmarks in any file underneath the working directory, though.\n\nIn order to use this feature, put this into your `.vimrc`:\n\n```viml\nlet g:bookmark_save_per_working_dir = 1\nlet g:bookmark_auto_save = 1\n```\n\nYou should add the filename `.vim-bookmarks` to your (global) `.gitignore` file so it doesn't get checked into version control.\n\nIf you want to customize the location or filename you can define the following function in your `.vimrc`. The return value will be used to retrieve and save the bookmark positions. This way you can implement you custom strategy for determining the work dir location (e.g. inside the `.git` directory):\n\n```viml\n\" Finds the Git super-project directory.\nfunction! g:BMWorkDirFileLocation()\n    let filename = 'bookmarks'\n    let location = ''\n    if isdirectory('.git')\n        \" Current work dir is git's work tree\n        let location = getcwd().'/.git'\n    else\n        \" Look upwards (at parents) for a directory named '.git'\n        let location = finddir('.git', '.;')\n    endif\n    if len(location) \u003e 0\n        return location.'/'.filename\n    else\n        return getcwd().'/.'.filename\n    endif\nendfunction\n```\n\n### Bookmarks per buffer\n\nThis feature implies `bookmark_auto_save`. When configured bookmarks will be\nloaded and saved on each buffer change. This allows working with different\nbuffers/tabs and keeping a different bookmark file for each one based on the\nfile open in the buffer. I.e., using the following function and having files\nfrom different Git repositories open in different tabs will use a different\nbookmarks file per Git repository.\n\nThis is different from how saving per working directory works because it allows\nfor having different bookmarks for different buffers/tabs open in the same\nwindow without having the working directory change automatically when switching\nbetween them.\n\nThe following function is similar to the one shown above (finds the .git folder\nlocation, defaults to current file's directory) :\n```viml\n\" Finds the Git super-project directory based on the file passed as an argument.\nfunction! g:BMBufferFileLocation(file)\n    let filename = 'vim-bookmarks'\n    let location = ''\n    if isdirectory(fnamemodify(a:file, \":p:h\").'/.git')\n        \" Current work dir is git's work tree\n        let location = fnamemodify(a:file, \":p:h\").'/.git'\n    else\n        \" Look upwards (at parents) for a directory named '.git'\n        let location = finddir('.git', fnamemodify(a:file, \":p:h\").'/.;')\n    endif\n    if len(location) \u003e 0\n        return simplify(location.'/.'.filename)\n    else\n        return simplify(fnamemodify(a:file, \":p:h\").'/.'.filename)\n    endif\nendfunction\n```\n\n### Silent saving and loading\n\nCall functions BookmarkSave, BookmarkLoad and BookmarkClearAll with the last argument set to 0 to perform these operations silently. You may use this to manage your bookmark list transparently from within your custom script.\n\n## Unite Integration\n![A screenshot of vim-bookmarks' Unite interface](./screenshot-unite-interface.png)\n\n[Unite](https://github.com/Shougo/unite.vim) is a multi-purpose user-interface plugin platform. Vim-bookmarks provides a Unite source called `vim_bookmarks` so users who use Unite will handle bookmarks with the Unite interface.\n\nAdditionally, when showing all your bookmarks, Unite is detected and the plugin will open `:Unite vim_bookmarks` instead of Vim's quickfix window. Note that `g:bookmark_auto_close` is no longer applied. Once opened, the window is managed by Unite.\n\nTo set a global per-source context setting, that will apply to Unite's vim_bookmarks source everytime it's opened, you can add this to your `vimrc`:\n\n```viml\ncall unite#custom#profile('source/vim_bookmarks', 'context', {\n\t\\   'winheight': 13,\n\t\\   'direction': 'botright',\n\t\\   'start_insert': 0,\n\t\\   'keep_focus': 1,\n\t\\   'no_quit': 1,\n\t\\ })\n```\n\nWith the Unite interface, when you select bookmarks, you can perform the following actions:\n\n* Open the selected bookmarks in various ways (open to the right, open above, open in new tab, etc.)\n* Yank the informations of selected bookmarks (path and line number, the line content, annotation, etc.)\n* Highlight the lines of the selected bookmarks\n* Replace the contents of selected bookmarks with [vim-qfreplace](https://github.com/thinca/vim-qfreplace) interface\n* Delete the selected bookmarks\n* And more...\n\nSee the screenshot below to get an idea of what you can do with the interface (the picture shows only a fraction, that means you can select even more actions):\n\n![A screenshot of action list of vim-bookmarks' Unite interface](./screenshot-unite-interface-actions.png)\n\nFor more information about Unite, start reading `:help Unite`.\n\n## CtrlP Integration\n\n[ctrlp.vim](https://github.com/ctrlpvim/ctrlp.vim) is a Full path fuzzy file, buffer, mru, tag, ... finder for Vim.\n\nAdditionally, when showing all your bookmarks, CtrlP is detected and the plugin will open `:CtrlPBookmark` instead of Vim's quickfix window. Note that `g:bookmark_auto_close` is no longer applied. Once opened, the window is managed by CtrlP.\n\nWith the CtrlP interface, when you select bookmarks, you can perform the following actions:\n* Open the selected bookmarks in various ways (open to the right, open above, open in new tab, etc.)\n* And more...\n\n## FAQ\n\n\u003e Why are the colours in the sign column weird?\n\nYour colorscheme is configuring the `SignColumn` highlight group weirdly. To change that add this to your `.vimrc`: `highlight SignColumn ctermbg=whatever`.\n\n\u003e What happens if I also use another plugin which uses signs (e.g. Syntastic)?\n\nVim only allows one sign per line. Therefore bookmarks will override any existing sign. When removing the bookmark the original sign will show up again. In other words vim-bookmarks won't remove another plugin's signs.\n\n\u003e Why aren't any signs showing at all?\n\nMake sure your vim supports signs: `:echo has('signs')` should give `1`\n\n\u003e How do I avoid keybinding conflicts with the Nerdtree plugin?\n\nYou could unbind the keys whenever Nerdtree becomes active (thanks to [@Nitive](https://github.com/Nitive)).\n\n```viml\nlet g:bookmark_no_default_key_mappings = 1\nfunction! BookmarkMapKeys()\n    nmap mm :BookmarkToggle\u003cCR\u003e\n    nmap mi :BookmarkAnnotate\u003cCR\u003e\n    nmap mn :BookmarkNext\u003cCR\u003e\n    nmap mp :BookmarkPrev\u003cCR\u003e\n    nmap ma :BookmarkShowAll\u003cCR\u003e\n    nmap mc :BookmarkClear\u003cCR\u003e\n    nmap mx :BookmarkClearAll\u003cCR\u003e\n    nmap mkk :BookmarkMoveUp\n    nmap mjj :BookmarkMoveDown\nendfunction\nfunction! BookmarkUnmapKeys()\n    unmap mm\n    unmap mi\n    unmap mn\n    unmap mp\n    unmap ma\n    unmap mc\n    unmap mx\n    unmap mkk\n    unmap mjj\nendfunction\nautocmd BufEnter * :call BookmarkMapKeys()\nautocmd BufEnter NERD_tree_* :call BookmarkUnmapKeys()\n```\n\n\u003e Why do my bookmarks disappear when running the `:make` command?\n\nBy default, the bookmark list is shown using the quickfix window, which can sometimes conflict with other commands. The location list may be used to show the bookmark list instead by setting the `g:bookmark_location_list` option documented above.\n\n## Changelog\n\nSee the [release page](https://github.com/MattesGroeger/vim-bookmarks/releases) for all changes.\n\n## Credits \u0026 Contribution\n\nThis plugin was developed by [Mattes Groeger][blog] under the [MIT License][license]. Pull requests are very welcome.\n\nThe following plugins were a great inspiration to me:\n* [vmark.vim][vmark] by Michael Zhou\n* [vim-gitgutter][gitgutter] by Andrew Stewart\n\n\n  [pathogen]: https://github.com/tpope/vim-pathogen\n  [vundle]: https://github.com/gmarik/vundle\n  [neobundle]: https://github.com/Shougo/neobundle.vim\n  [vimplug]: https://github.com/MattesGroeger/vim-plug\n  [macvim]: http://code.google.com/p/macvim/\n  [license]: https://github.com/MattesGroeger/vim-bookmarks/blob/master/LICENSE\n  [blog]: http://blog.mattes-groeger.de\n  [vmark]: http://www.vim.org/scripts/script.php?script_id=4076\n  [gitgutter]: https://github.com/airblade/vim-gitgutter\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMattesGroeger%2Fvim-bookmarks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMattesGroeger%2Fvim-bookmarks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMattesGroeger%2Fvim-bookmarks/lists"}