{"id":13412948,"url":"https://github.com/b3nj5m1n/kommentary","last_synced_at":"2025-04-04T20:11:09.566Z","repository":{"id":39413754,"uuid":"334279490","full_name":"b3nj5m1n/kommentary","owner":"b3nj5m1n","description":"Neovim commenting plugin, written in lua.","archived":false,"fork":false,"pushed_at":"2023-11-29T13:34:53.000Z","size":136,"stargazers_count":533,"open_issues_count":8,"forks_count":13,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-07-31T20:51:42.720Z","etag":null,"topics":["comment","commenting","lua","neovim","neovim-lua","neovim-plugin","nvim","plugin"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/b3nj5m1n.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}},"created_at":"2021-01-29T22:41:19.000Z","updated_at":"2024-07-09T13:35:35.000Z","dependencies_parsed_at":"2024-01-03T03:33:00.166Z","dependency_job_id":"d9c3c766-a8c7-4229-acd9-5f0926784ffb","html_url":"https://github.com/b3nj5m1n/kommentary","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/b3nj5m1n%2Fkommentary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b3nj5m1n%2Fkommentary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b3nj5m1n%2Fkommentary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b3nj5m1n%2Fkommentary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/b3nj5m1n","download_url":"https://codeload.github.com/b3nj5m1n/kommentary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242678,"owners_count":20907134,"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":["comment","commenting","lua","neovim","neovim-lua","neovim-plugin","nvim","plugin"],"created_at":"2024-07-30T20:01:31.481Z","updated_at":"2025-04-04T20:11:09.547Z","avatar_url":"https://github.com/b3nj5m1n.png","language":"Lua","funding_links":[],"categories":["Editing Support","Lua"],"sub_categories":["Comment"],"readme":"# kommentary\n\nNeovim plugin to comment text in and out, written in lua. Supports commenting out the current line, a visual selection and a motion.\n\n![](https://web.archive.org/web/20220712113235/https://camo.githubusercontent.com/a91807453086b1616b6215875fbea95cd406d6a26c8c2bda8844f693a3cd9d18/68747470733a2f2f7331302e67696679752e636f6d2f696d616765732f5065656b2d323032312d30312d33302d32332d31322e676966)\n\n## Note\n\nUnfortunately, **I will not be adding any more features to kommentary**. I'll do my best to fix any problems, should they occur in the future.\n\nThere are several reasons for this decision, first and foremost, the codebase is really not fun to work on anymore and badly needs a rewrite. There are basically no unit tests, and some of the documentation is outdated. The whole structure is flawed, so implementing new features is a pain.\n\nThere's also a new plugin called [Comment.nvim](https://github.com/numToStr/Comment.nvim), it's also written entirely in lua, it seems to support everything kommentary supports, in addition to dot (`.`) repeat and operating on parts of a line instead of the whole line. It has significantly more contributors and seems to be actively developed. Sadly, this also seems to make kommentary obsolete.\n\nThanks to everyone who has contributed over the course of the last 2 years. ✌️\n\n## Getting started\n\n### Requirements\n\n- Neovim 0.5+\n\n### Install\nYou can install the plugin using your favorite plugin manager, just make sure you remove any plugins that might conflict with this one, such as vim-commentary.\n\n#### Packer\n\n```lua\nuse 'b3nj5m1n/kommentary'\n```\n\n#### Vim-Plug\n\n```viml\nPlug 'b3nj5m1n/kommentary'\n```\n\n### Default Keybindings\n\nThe default keybindings are the same as in vim-commentary. That means you can toggle comments for the current line using gcc, for the current visual selection using gc, and in combination with a motion using gc, for example gc5j.\n\nThere's also some more advanced mappings which you can activate if you put this in your init.lua:\n\n```lua\nrequire('kommentary.config').use_extended_mappings()\n```\n\nThe new mappings are:\n\n* leader cic will increase commenting level for the current line, \u003cleader\u003eci will do the same for a visual selection or motion\n* leader cdc will decrease commenting level for the current line, \u003cleader\u003edi will do the same for a visual selection or motion\n\nWhich behind the scenes calls the following chunk of code, which you could also execute yourself with keybindings of your choice:\n```lua\nvim.api.nvim_set_keymap(\"n\", \"\u003cleader\u003ecic\", \"\u003cPlug\u003ekommentary_line_increase\", {})\nvim.api.nvim_set_keymap(\"n\", \"\u003cleader\u003eci\", \"\u003cPlug\u003ekommentary_motion_increase\", {})\nvim.api.nvim_set_keymap(\"x\", \"\u003cleader\u003eci\", \"\u003cPlug\u003ekommentary_visual_increase\", {})\nvim.api.nvim_set_keymap(\"n\", \"\u003cleader\u003ecdc\", \"\u003cPlug\u003ekommentary_line_decrease\", {})\nvim.api.nvim_set_keymap(\"n\", \"\u003cleader\u003ecd\", \"\u003cPlug\u003ekommentary_motion_decrease\", {})\nvim.api.nvim_set_keymap(\"x\", \"\u003cleader\u003ecd\", \"\u003cPlug\u003ekommentary_visual_decrease\", {})\n```\n\nIf you don't want to use the default mappings, you can disable the creation of those using the `kommentary_create_default_mappings` variable. Be sure to set the value *before* the plugin is loaded though.\n```lua\nvim.g.kommentary_create_default_mappings = false\n```\n\nYou can then map those actions yourself (You might need to do that *after* the plugin is loaded), for example:\n```lua\nvim.api.nvim_set_keymap(\"n\", \"\u003cleader\u003ecc\", \"\u003cPlug\u003ekommentary_line_default\", {})\nvim.api.nvim_set_keymap(\"n\", \"\u003cleader\u003ec\", \"\u003cPlug\u003ekommentary_motion_default\", {})\nvim.api.nvim_set_keymap(\"x\", \"\u003cleader\u003ec\", \"\u003cPlug\u003ekommentary_visual_default\", {})\n```\n\nOriginally, commenting in visual mode would not cancel the selection, after many requests this has been changed to the default behavior of vim-commentary. If you want the old behavior, disable the creation of the default mappings and then load the old ones:\n\n```lua\nvim.api.nvim_set_keymap(\"n\", \"gcc\", \"\u003cPlug\u003ekommentary_line_default\", {})\nvim.api.nvim_set_keymap(\"n\", \"gc\", \"\u003cPlug\u003ekommentary_motion_default\", {})\nvim.api.nvim_set_keymap(\"v\", \"gc\", \"\u003cPlug\u003ekommentary_visual_default\u003cC-c\u003e\", {})\n```\n\n## Configuration\n\nFor most users, configuration should hardly be necessary, I try to provide sane defaults and the plugin, once installed, can basically be used as a drop-in replacement for vim-commentary. That being said, maybe you have some different preferences, or you like your editor heavily customised, this plugin should still have you covered.\n\nThe config module provides a convenience function called `configure_language` which makes it easy to configure a language.\n\n### Configure unsupported language\n\nMost languages have basic support out of the box, thanks to `commentstring`.\nUnfortunately however, for some languages `commentstring` is not set.\nAlso, `commentstring` supports either single-line or multi-line comments, not both.\nFor those reasons, you might prefer to properly configure a language. You can do it like this:\n\n```lua\nlua \u003c\u003c EOF\nrequire('kommentary.config').configure_language(\"rust\", {\n    single_line_comment_string = \"//\",\n    multi_line_comment_strings = {\"/*\", \"*/\"},\n})\nEOF\n```\n\nIf one of those two is not supported by the language, set the value to false, otherwise the default (`//` for single-line and `{/*,*/}` for multi-line) will be used.\n\n### Always use single/multi-line comments\n\nSome languages might technically support multi-line comments but have some quirks with them, or maybe you just prefer single-line comments. The proper way to configure this is:\n\n```lua\nlua \u003c\u003c EOF\nrequire('kommentary.config').configure_language(\"rust\", {\n    prefer_single_line_comments = true,\n})\nEOF\n```\n\nIt also works the other way:\n\n```lua\nlua \u003c\u003c EOF\nrequire('kommentary.config').configure_language(\"rust\", {\n    prefer_multi_line_comments = true,\n})\nEOF\n```\n\nIf you set both of them to true, it will use the default.\n\nYou can also set global defaults, these will be used for all languages, unless you overwrite it for that specific language like shown above:\n```lua\nlua \u003c\u003c EOF\nrequire('kommentary.config').configure_language(\"default\", {\n    prefer_single_line_comments = true,\n})\nEOF\n```\n\n### More configuration options\n\nThe `configure_language` provides access to two other options, `use_consistent_indentation` and `ignore_whitespace`. Both are set to true by default, but of course you can overwrite that.\n\n#### `use_consistent_indentation`\n\n`use_consistent_indentation` will cause blocks commented in with `prefer_single_line_comments` enabled to all have the comment prefix in the same column:\n\n```lua\n-- local function example()\n--    print(\"Example\")\n-- end\n```\nInstead of\n```lua\n-- local function example()\n    -- print(\"Example\")\n-- end\n```\n\n#### `ignore_whitespace`\n\n`ignore_whitespace` will cause lines that don't contain anything to be ignored, it's as simple as that.\n\n```lua\n-- function test_function_1()\n--     print(\"test\")\n-- end\n\n-- function test_function_2()\n--     print(\"test\")\n-- end\n```\nInstead of\n```lua\n-- function test_function_1()\n--     print(\"test\")\n-- end\n--\n-- function test_function_2()\n--     print(\"test\")\n-- end\n```\n\n### Configure multiple languages at once\n\nThanks to @pedro757, you can also set the same options for multiple languages by supplying a list of languages:\n\n```lua\nlua \u003c\u003c EOF\nrequire('kommentary.config').configure_language({\"c\", \"rust\"}, {\n    prefer_single_line_comments = true,\n})\nEOF\n```\n\n### Advanced configuration\n\nThis plugin allows for very individual configuration, pretty much every operation the plugin does is broken up into smaller functions, all of which are exposed and can be called in a custom function, which you can easily assign to a mapping of your choice, meaning you can incorporate some of the functionality of this plugin into your own lua functions.\nFor more information, you can either read the source code (I do my best to leave helpful comments) or build the [documentation](README.md#Documentation).\n\nHere is a simple example in which this plugin only plays a minor role, so it should be easy to understand (If you're a little familiar with neovim's lua api). We'll create mapping that, when called, inserts a new comment under the current line and puts us in insert mode.\n\n```lua\nlocal config = require('kommentary.config')\nlocal M = {}\n\n--[[ This function will be called automatically by the mapping, the first\nargument will be the line that is being operated on. ]]\nfunction M.insert_comment_below(...)\n    local args = {...}\n    -- This includes the commentstring\n    local configuration = config.get_config(0)\n    local line_number = args[1]\n    -- Get the current content of the line\n    local content = vim.api.nvim_buf_get_lines(0, line_number-1, line_number, false)[1]\n    --[[ Get the level of indentation of that line (Find the index of the\n    first non-whitespace character) ]]\n    local indentation = string.find(content, \"%S\")\n    --[[ Create a string with that indentation, with a dot at the end so that\n    kommentary respects that indentation ]]\n    local new_line = string.rep(\" \", indentation-1) .. \".\"\n    -- Insert the new line underneath the current one\n    vim.api.nvim_buf_set_lines(0, line_number, line_number, false, {new_line})\n    -- Comment in the new line\n    require('kommentary.kommentary').comment_in_line(line_number+1, configuration)\n    -- Set the cursor to the correct position\n    vim.api.nvim_win_set_cursor(0, {vim.api.nvim_win_get_cursor(0)[1]+1, #new_line+2})\n    -- Change the char under cursor (.)\n    vim.api.nvim_feedkeys(\"cl\", \"n\", false)\nend\n\n--[[ This is a method provided by kommentary's config, it will take care of\nsetting up a \u003cPlug\u003e mapping. The last argument is the optional callback\nfunction, meaning when we execute this mapping, this function will be\ncalled instead of the default. --]]\nconfig.add_keymap(\"n\", \"kommentary_insert_below\", config.context.line, { expr = true }, M.insert_comment_below)\n-- Set up a regular keymapping to the new \u003cPlug\u003e mapping\nvim.api.nvim_set_keymap('n', '\u003cleader\u003eco', '\u003cPlug\u003ekommentary_insert_below', { silent = true })\n\nreturn M\n```\n\n\n## Contributing\n\nAny and all contributions are greatly appreciated!\n\n### Issues\n\nIf you found a bug or want to request a feature, pleases do so by [raising an issue](https://github.com/b3nj5m1n/kommentary/issues/new/choose).\n\n### Pull Requests\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b amazing_feature`)\n3. Make your changes\n4. Commit your Changes (`git commit -m 'Add some amazing feature'`)\n5. Push to the Branch (`git push origin amazing_feature`)\n6. Open a Pull Request\n\nPlease try your best to follow the style of the rest of the codebase, even though there's no official spec or linter for\nit. (Try not to exceed 80 characters per line, use snake_case)\n\n### Documentation\n\nThe code is heavily commented, functions are documented using [LDoc](https://github.com/lunarmodules/LDoc).\n\nYou can build the documentation with this command:\n```\nldoc .\n```\nThen you can access it from doc/index.html\n\n### Tests\n\nThanks to @YodaEmbedding, there are now proper unit tests available.\n\nMake sure [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) is installed, then navigate to the lua directory.\n\nFrom here, you can run the tests with the following command:\n\n```bash\nnvim --headless -c \"PlenaryBustedDirectory test/\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fb3nj5m1n%2Fkommentary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fb3nj5m1n%2Fkommentary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fb3nj5m1n%2Fkommentary/lists"}