{"id":16811665,"url":"https://github.com/philrunninger/bufselect","last_synced_at":"2025-03-17T10:47:10.396Z","repository":{"id":19800995,"uuid":"87952129","full_name":"PhilRunninger/bufselect","owner":"PhilRunninger","description":"A minimalist buffer explorer for Neovim/Vim","archived":false,"fork":false,"pushed_at":"2024-10-10T13:13:11.000Z","size":380,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-23T20:31:46.186Z","etag":null,"topics":["buffer","explorer","vim-plugin"],"latest_commit_sha":null,"homepage":"","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/PhilRunninger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2017-04-11T15:45:29.000Z","updated_at":"2024-10-10T13:13:14.000Z","dependencies_parsed_at":"2023-10-16T22:33:27.112Z","dependency_job_id":"f860c6ef-8e1f-41da-86e7-a8b6fcabff8b","html_url":"https://github.com/PhilRunninger/bufselect","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilRunninger%2Fbufselect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilRunninger%2Fbufselect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilRunninger%2Fbufselect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilRunninger%2Fbufselect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhilRunninger","download_url":"https://codeload.github.com/PhilRunninger/bufselect/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244021478,"owners_count":20385122,"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":["buffer","explorer","vim-plugin"],"created_at":"2024-10-13T10:19:23.951Z","updated_at":"2025-03-17T10:47:10.370Z","avatar_url":"https://github.com/PhilRunninger.png","language":"Vim Script","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BufSelect\n\n## Summary\n\n**BufSelect** is a minimalist buffer switcher plugin for Vim or Neovim. It was inspired by [bufexplorer](https://github.com/jlanzarotta/bufexplorer) and [buffergator](https://github.com/jeetsukumaran/vim-buffergator), but with some of their advanced functionality removed. What **BufSelect** ended up being is:\n\n* A [single command](#command) to kick things off.\n* A simple list in a floating window, showing the current working directory, and buffer number, filename, and relative path of all listed buffers.\n    ![image](media/darkScreenshot.png)\n    \u003cbr\u003e**Figure 1**: BufSelect with a dark colorscheme\n\n* A few [key mappings](#key-mappings) to open, find, or delete buffers, sort the list, change working directory, and quickly navigate the list.\n* Other settings define [sort order](#sort-order) and [window customizations](#window-customizations).\n\n## Installation\n\nUse your favorite plugin manager. If you don't have one, try one of these: [vim-pathogen](https://github.com/tpope/vim-pathogen), [vim-plug](https://github.com/junegunn/vim-plug), [Packer.nvim](https://github.com/wbthomason/packer.nvim) or [lazy.nvim](https://github.com/folke/lazy.nvim). Alternatively, you can use packages and submodules, as Greg Hurrell ([@wincent](https://github.com/wincent)) describes in his excellent Youtube video: [Vim screencast #75: Plugin managers](https://www.youtube.com/watch?v=X2_R3uxDN6g)\n\n## Compatibility\n\nThe `master` branch of this plugin is no longer compatible with Vim, and all new development will target Neovim. If you are using Vim 8+, you can still use this plugin without all the newer functionality; just checkout the `vim-compatible` branch.\n\n## Command\n\nThe only command is **`:ShowBufferList`**, which can be assigned to a key. The mapping is not done by this plugin, so as not to interfere with your existing mappings. Here's an example of how you would map the command:\n```vim\n\" vimscript\nnnoremap \u003csilent\u003e \u003cleader\u003eb :ShowBufferList\u003cCR\u003e\n```\n```lua\n-- lua\nvim.api.nvim_set_keymap('n', '\u003cleader\u003eb', ':ShowBufferList\u003cCR\u003e', {noremap=true, slient=true})\n```\n\n## Settings\n\nSettings for **BufSelect** are defined in a dictionary that is passed as a parameter to the `bufselect#settings` autoload function. The structure of the dictionary follows. Only the settings you want to override need to be specified. All others will use the default values, which are shown here.\n\n```vim\n{\n  \"mappings\": {\n    \"open\":    \"o\",\n    \"split\":   \"s\",\n    \"vsplit\":  \"v\",\n    \"tab\":     \"t\",\n    \"gopen\":   \"go\",\n    \"gsplit\":  \"gs\",\n    \"gvsplit\": \"gv\",\n    \"gtab\":    \"gt\",\n    \"exit\":    \"q\",\n    \"find\":    \"f\",\n    \"delete\":  \"x\",\n    \"sort\":    \"S\",\n    \"cd\":      \"cd\",\n    \"cdup\":    \"..\",\n    \"next\":    \"#\"\n  },\n  \"sortOrder\": \"Name\",\n  \"win\": {\n    \"config\": {\"border\": \"double\"},\n    \"hl\":     \"\"\n  }\n}\n```\nHere is the syntax for calling the `bufselect#settings` function, from either vimscript or lua.\n```vim\n\" vimscript\ncall bufselect#settings({\n    \\ \"mappings\": {\"delete\":\"w\", \"open\":\"l\", \"gopen\":\"gl\"},\n    \\ \"win\": {\"config\": {\"border\":\"rounded\", \"title\":\"Buffers\", \"title_pos\":\"center\"}}\n\\ })\n```\n```lua\n-- lua\nvim.fn['bufselect#settings']({\n    mappings= {delete=\"w\", open=\"l\", gopen=\"gl\"},\n    win= {config= {border=\"rounded\", title=\"Buffers\", title_pos=\"center\"}}\n})\n```\n\n### Key Mappings\n\nThe `'mappings'` part of dictionary defines key mappings that work only within **BufSelect**. They perform the following functions:\n\n| Dictionary Key | Function |\n| :-: | --- |\n| `\"open\"`    | Open the buffer in the current window, meaning the one under the **BufSelect** floating window. |\n| `\"split\"`   | Open the buffer in a new horizontal split. |\n| `\"vsplit\"`  | Open the buffer in a new vertical split. |\n| `\"tab\"`     | Open the buffer in a new tab. |\n| | |\n| `\"gopen\"`   | Preview the buffer in the current window, keeping **BufSelect** open. |\n| `\"gsplit\"`  | Preview the buffer in a new horizontal split, keeping **BufSelect** open. |\n| `\"gvsplit\"` | Preview the buffer in a new vertical split, keeping **BufSelect** open. |\n| `\"gtab\"`    | Preview the buffer in a new tab, keeping **BufSelect** open. |\n| | |\n| `\"find\"`    | Find the buffer in any open window, and go there. |\n| `\"delete\"`  | Close the buffer using vim's `bwipeout` command. |\n| `\"sort\"`    | Change the sort order. |\n| `\"cd\"`      | Change working directory to match the buffer's. |\n| `\"cdup\"`    | Change working directory up one level from current. |\n| `\"next\"`    | Move cursor to the next listed open buffer. |\n| `\"exit\"`    | Exit the buffer list. |\n\nSome other mappings are non-configurable. They are:\n\n| Mapping | Function |\n| :-: | --- |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | opens a buffer in the current window. It's the same as `'open'`. |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | exits the buffer list - the same as `'exit'`. |\n| \u003ckbd\u003e0\u003c/kbd\u003e...\u003ckbd\u003e9\u003c/kbd\u003e | moves the cursor to the next buffer matching the cumulatively-typed buffer number. See **Figure 2** below for illustration.\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;1. Typing \u003ckbd\u003e3\u003c/kbd\u003e will search for and find buffer **33**, the next one starting with **3**.\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;2. Then typing \u003ckbd\u003e6\u003c/kbd\u003e will search for and find buffer **36**.\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;3a. Then pressing \u003ckbd\u003e1\u003c/kbd\u003e will look for buffer **361**.\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;3b. **361** doesn't exist, so drop the leading search digit and look for **61**.\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;3c. **61** doesn't exist either, so drop the **6** and look for buffer **1**, which does exist. The search is over. |\n| \u003ckbd\u003e?\u003c/kbd\u003e | shows/hides short descriptions of all mappings. |\n\n![image](media/lightScreenshot.png)\n\u003cbr\u003e**Figure 2**: Using a light colorscheme, and showing the help text.\n\n### Sort Order\nThe initial sort order is set by the `'sortOrder'` setting. Valid values are `'Num'`, `'Status'`, `'Name'`, `'Extension'`, and `'Path'`.\n\n`'Status'` refers to whether a buffer is loaded or visible. See [:help :ls](https://neovim.io/doc/user/windows.html#%3Als), which states:\n\n* `a` an active buffer: it is loaded and visible\n* `h` a hidden buffer: it is loaded, but currently not displayed in a window\n* ` `(space) indicates a file that's been added (see [:help :badd](https://neovim.io/doc/user/windows.html#%3Abadd)), but is not yet loaded.\n\n### Window Customizations\n\nThe **BufSelect** floating window can be customized two different ways in the `'win'` dictionary, which contains these two items:\n\n1. The `'config'` dictionary lets you change things like the border and title of the window. Check out [:help nvim_open_win()](https://neovim.io/doc/user/api.html#nvim_open_win()) for more for details. Example:\n\n    ```vim\n    \" vimscript\n    call bufselect#settings({'win': {'config': {'border':'single', 'title':'Buffers:'}}})\n    ```\n    ```lua\n    -- lua\n    vim.fn['bufselect#settings']({win= {config= {border='single', title='Buffers:'}}})\n    ```\n\n    ![image](media/floatwinconfig.png)\n    \u003cbr\u003e**Figure 3**: Custom Window Attributes: single border and a title\n\n1. The `'hl'` string setting is used to override highlighting. Read [:help 'winhl'](https://neovim.io/doc/user/options.html#'winhl') to see how it works. For example, if your colorscheme doesn't define `NormalFloat`, you can use this to make it look like the normal background. It also works to link the **BufSelect** highlight groups to other highlight groups. Both scenarios are shown in this example:\n\n    ```vim\n    \" vimscript\n    call bufselect#settings({'win': {'hl': 'NormalFloat:Normal,BufSelectCurrent:Keyword'}})\n    ```\n    ```lua\n    -- lua\n    vim.fn['bufselect#settings']({win= {hl='NormalFloat:Normal,BufSelectCurrent:Keyword'}})\n    ```\n\n    The highlight groups defined for **BufSelect** are:\n\n    * `BufSelectSort` - the sort indicator\n    * `BufSelectCurrent` - the current buffer (also indicated by a `%`) and the current working directory\n    * `BufSelectAlt` - the alternate buffer (also indicated by a `#`)\n    * `BufSelectUnsaved` - unsaved buffers (also indicated by a `+`)\n    * `BufSelectHelp` - the question mark in `? for help`, and the list of mapped keys in the help text\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilrunninger%2Fbufselect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilrunninger%2Fbufselect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilrunninger%2Fbufselect/lists"}