{"id":13485276,"url":"https://github.com/andymass/vim-matchup","last_synced_at":"2025-05-14T08:07:14.845Z","repository":{"id":37412807,"uuid":"107318862","full_name":"andymass/vim-matchup","owner":"andymass","description":"vim match-up: even better % :facepunch: navigate and highlight matching words :facepunch: modern matchit and matchparen.  Supports both vim and neovim + tree-sitter.","archived":false,"fork":false,"pushed_at":"2025-03-30T13:41:35.000Z","size":896,"stargazers_count":1773,"open_issues_count":55,"forks_count":71,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-12T00:53:26.484Z","etag":null,"topics":["highlighting-matches","matching-pairs","matchparen","motions","nvim-treesitter","parenthesis-matching","vim","vim-plugin","vimscript-5624"],"latest_commit_sha":null,"homepage":"https://www.vim.org/scripts/script.php?script_id=5624","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/andymass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2017-10-17T20:13:04.000Z","updated_at":"2025-04-11T20:57:11.000Z","dependencies_parsed_at":"2023-12-19T16:14:02.729Z","dependency_job_id":"b23ff1ce-c1cb-4909-b0f6-465bfbf9ef7d","html_url":"https://github.com/andymass/vim-matchup","commit_stats":{"total_commits":691,"total_committers":54,"mean_commits":"12.796296296296296","dds":0.1085383502170767,"last_synced_commit":"aca23ce53ebfe34e02c4fe07e29e9133a2026481"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andymass%2Fvim-matchup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andymass%2Fvim-matchup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andymass%2Fvim-matchup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andymass%2Fvim-matchup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andymass","download_url":"https://codeload.github.com/andymass/vim-matchup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101618,"owners_count":22014909,"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":["highlighting-matches","matching-pairs","matchparen","motions","nvim-treesitter","parenthesis-matching","vim","vim-plugin","vimscript-5624"],"created_at":"2024-07-31T17:01:53.716Z","updated_at":"2025-05-14T08:07:09.824Z","avatar_url":"https://github.com/andymass.png","language":"Vim Script","funding_links":[],"categories":["Vim Script","Vim script"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cp\u003e\n\u003cimg src='https://github.com/andymass/matchup.vim/wiki/images/teaser.jpg' width='250px' alt='and in this corner...' /\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n\u003ch1 align=\"center\"\u003e\n  vim match-up :fist_right::fist_left:\n\u003c/h1\u003e\n\nmatch-up is a plugin that lets you highlight, navigate, and operate on\nsets of matching text.  It extends vim's `%` key to language-specific\nwords instead of just single characters.\n\n## Screenshot\n\n\u003cimg src='https://raw.githubusercontent.com/wiki/andymass/vim-matchup/images/match-up-hl1.gif' width='450px'\u003e\n\n## Table of contents\n\n  * [Overview](#overview)\n  * [Installation](#installation)\n  * [Features](#features)\n  * [Options](#options)\n  * [FAQ](#faq)\n  * [Interoperability](#interoperability)\n  * [Acknowledgments](#acknowledgments)\n  * [Development](#development)\n\n## Overview\n\nmatch-up can be used as a drop-in replacement for the classic plugin [matchit.vim].\nmatch-up aims to enhance all of matchit's features, fix a number of its\ndeficiencies and bugs, and add a few totally new features.  It also\nreplaces the standard plugin [matchparen], allowing all of matchit's words\nto be highlighted along with the `matchpairs` (`(){}[]`).\n\n[matchit.vim]: http://ftp.vim.org/pub/vim/runtime/macros/matchit.txt\n[matchparen]: http://ftp.vim.org/pub/vim/runtime/doc/pi_paren.txt\n\nSee [detailed feature documentation](#detailed-feature-documentation) for\nmore information.  This plugin:\n\n- Extends vim's `%` motion to language-specific words.  The following vim\n  file type plugins currently provide special support for match-up:\n\n  \u003e abaqus, ada, aspvbs, bash, c, cpp, chicken, clojure, cmake, cobol,\n  \u003e context, csc, csh, dtd, dtrace, eiffel, eruby, falcon, fortran,\n  \u003e framescript, haml, hamster, hog, html, ishd, j, javascript,\n  \u003e javascriptreact, jsp, kconfig, liquid, lua, m3quake, make, matlab, mf,\n  \u003e modula2, modula3, mp, nsis, ocaml, pascal, pdf, perl, php, plaintex,\n  \u003e postscr, ruby, sh, spec, sql, tex (latex), typescriptreact, vb,\n  \u003e verilog, vhdl, vim, xhtml, xml, zimbu, zsh\n\n  Other file types can be supported by installing additional filetype\n  plugins (not provided by match-up).\n\n  Note: match-up uses the same `b:match_words` as matchit.\n\n- Adds motions `g%`, `[%`, `]%`, and `z%`.\n- Combines these motions into convenient text objects `i%` and `a%`.\n- Highlights symbols and words under the cursor which `%` can work on,\n  and highlights matching symbols and words.  Now you can easily tell\n  where `%` will jump to.\n\n## Installation\n\nIf you use [vim-plug](https://github.com/junegunn/vim-plug), then add the\nfollowing line to your vimrc's plugin section:\n\n```vim\nPlug 'andymass/vim-matchup'\n```\n\nand then use `:PlugInstall`.\n\nOr, if you use [packer](https://github.com/wbthomason/packer.nvim), add\nit to your init.vim\n\n```lua\nreturn require('packer').startup(function(use)\n  use {\n    'andymass/vim-matchup',\n    setup = function()\n      -- may set any options here\n      vim.g.matchup_matchparen_offscreen = { method = \"popup\" }\n    end\n  }\nend)\n```\n\nand run `:PackerSync` or similar.\n\nSee [Tree-sitter integration](https://github.com/andymass/vim-matchup#tree-sitter-integration)\nfor information on how to enable tree-sitter matching with neovim.\n\nNote: I do not recommend using alternative loading strategies such as\n`event = 'VimEnter'` or `event = 'CursorMoved'` as match-up already\nloads a minimal amount of code on start-up.  It may work, but if you run\ninto issues, remove the event key as a first debugging step.\n\nWith [LunarVim](https://www.lunarvim.org/), tree-sitter integration can be\nenabled as follows:\n\n```lua\n{\n  \"andymass/vim-matchup\",\n  setup = function()\n    vim.g.matchup_matchparen_offscreen = { method = \"popup\" }\n  end,\n},\n\nlvim.builtin.treesitter.matchup.enable = true\n```\n\nYou can use any other plugin manager such as\n[vundle](https://github.com/gmarik/vundle),\n[dein](https://github.com/Shougo/dein.vim),\n[neobundle](https://github.com/Shougo/neobundle.vim), or\n[pathogen](https://github.com/tpope/vim-pathogen),\n\nmatch-up should automatically disable matchit and matchparen, but if you\nare still having trouble, try placing this near the top of your vimrc:\n\n```vim\nlet g:loaded_matchit = 1\n```\n\nSee [Interoperability](#interoperability) for more information about working\ntogether with other plugins.\n\n### Tree-sitter integration\n\n_Note: Currently this feature is possible in neovim only.  Only the latest\nversion of neovim is supported._\n\nmatch-up has support for language syntax provided by tree-sitter.  The\nlist of supported languages is available\n[here](https://github.com/andymass/vim-matchup/tree/master/after/queries).\n\nThis feature requires manual opt-in in your init.vim and requires\n[nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) to\nbe installed.\n\n```vim\nPlug 'nvim-treesitter/nvim-treesitter'\nlua \u003c\u003cEOF\nrequire'nvim-treesitter.configs'.setup {\n  matchup = {\n    enable = true,              -- mandatory, false will disable the whole extension\n    disable = { \"c\", \"ruby\" },  -- optional, list of language that will be disabled\n    -- [options]\n  },\n}\nEOF\n```\n\nBeside `enable` and `disable`, the following options are available, all\ndefaulting to disabled:\n\n  - `disable_virtual_text`: do not use virtual text to highlight the\n  virtual end of a block, for languages without explicit end markers\n  (e.g., Python).\n  - `include_match_words`: additionally include traditional vim regex\n  matches for symbols.  For example, highlights `/* */` comments in C++\n  which are not supported in tree-sitter matching.\n\nScreenshot:\n\n\u003cimg src='https://user-images.githubusercontent.com/6655373/143594648-c178c4f0-24c3-4b81-a213-3e615dbd17c6.png' width='450px'\u003e\n\n## Features\n\n|         | feature                          | __match-up__   | matchit       | matchparen    |\n| ------- | -------------------------------- | -------------- | ------------- | ------------- |\n| ([a.1]) | jump between matching words      | :thumbsup:     | :thumbsup:    | :x:           |\n| ([a.2]) | jump to open \u0026 close words       | :thumbsup:     | :thumbsup:    | :x:           |\n| ([a.3]) | jump inside (`z%`)               | :thumbsup:     | :x:           | :x:           |\n| ([b.1]) | full set of text objects         | :thumbsup:     | :question:    | :x:           |\n| ([b.2]) | delete surrounding matched words | :thumbsup:     | :x:           | :x:           |\n| ([c.1]) | highlight `()`, `[]`, \u0026 `{}`     | :thumbsup:     | :x:           | :thumbsup:    |\n| ([c.2]) | highlight _all_ matching words   | :thumbsup:     | :x:           | :x:           |\n| ([c.3]) | display matches off-screen       | :thumbsup:     | :x:           | :x:           |\n| ([c.4]) | show where you are (breadcrumbs) | :thumbsup:     | :x:           | :x:           |\n| ([d.1]) | (neovim) tree-sitter integration | :thumbsup:     | :x:           | :x:           |\n\n[a.1]: #a1-jump-between-matching-words\n[a.2]: #a2-jump-to-open-and-close-words\n[a.3]: #a3-jump-inside\n[b.1]: #b1-full-set-of-text-objects\n[b.2]: #surroundings\n[c.1]: #c1-highlight---and-\n[c.2]: #c2-highlight-all-matches\n[c.3]: #c3-display-matches-off-screen\n[c.4]: #c4-where-am-i\n[d.1]: #tree-sitter-integration\n[inclusive]: #inclusive-and-exclusive-motions\n[exclusive]: #inclusive-and-exclusive-motions\n\nLegend: :thumbsup: supported.\n:question: poorly implemented, broken, or uncertain.  :x: not possible.\n\n### Detailed feature documentation\n\nWhat do we mean by open, close, mid?  This depends on the specific file\ntype and is configured through the variable `b:match_words`.  Here are a\ncouple examples:\n\n#### vim-script\n\n```vim\nif l:x == 1\n  call one()\nelseif l:x == 2\n  call two()\nelse\n  call three()\nendif\n```\n\nFor the vim-script language, match-up understands the words `if`,\n`else`, `elseif`, `endif` and that they form a sequential construct.  The\n\"open\" word is `if`, the \"close\" word is `endif`, and the \"mid\"\nwords are `else` and `elseif`.  The `if`/`endif` pair is called an\n\"open-to-close\" block and the `if`/`else`, `else`/`elsif`, and\n`elseif`/`endif` are called \"any\" blocks.\n\n#### C, C++\n```c\n#if 0\n#else\n#endif\n\nvoid some_func() {\n    if (true) {\n      one();\n    } else if (false \u0026\u0026 false) {\n      two();\n    } else {\n      three();\n    }\n}\n```\n\nSince in C and C++, blocks are delimited using braces (`{` \u0026 `}`),\nmatch-up will recognize `{` as the open word and `}` as the close word.\nIt will ignore the `if` and `else if` because they are not defined in\nvim's default C file type plugin.\n(Note: In neovim, this is optionally supported via\n[Tree-sitter](#tree-sitter-integration))\n\nOn the other hand, match-up will recognize the `#if`, `#else`, `#endif`\npreprocessor directives.\n\n#### (a.1) jump between matching words\n  - `%` go forwards to next matching word.  If at a close word,\n  cycle back to the corresponding open word.\n  - `{count}%` forwards `{count}` times.  Requires\n  `{count} \u003c= g:matchup_motion_override_Npercent`.  For larger\n  `{count}`, `{count}%` goes to the `{count}` percentage in the file.\n  - `g%` go backwards to `[count]`th previous matching word.  If at an\n  open word, cycle around to the corresponding close word.\n\n#### (a.2) jump to open and close words\n- `[%` go to `[count]`th previous outer open word.  Allows navigation\nto the start of blocks surrounding the cursor.  This is similar to vim's\nbuilt-in `[(` and `[{` and is an [exclusive] motion.\n- `]%` go to `[count]`th next surrounding close word.  This is an\n[exclusive] motion.\n\n#### (a.3) jump inside\n- `z%` go to inside `[count]`th nearest inner contained block.  This\n  is an [exclusive] motion when used with operators, except it eats\n  whitespace.  For example, where `█` is the cursor position,\n\n```vim\n  █ call somefunction(param1, param2)\n```\n`dz%` produces\n```vim\n  param1, param2)\n```\nbut in\n```vim\n  █ call somefunction(      param1, param2)\n```\n`dz%` also produces\n```vim\n  param1, param2)\n```\n\n#### (b.1) full set of text objects\n- `i%` the inside of an any block\n- `1i%` the inside of an open-to-close block\n- `{count}i%` If count is greater than 1, the inside of the `{count}`th\n  surrounding open-to-close block\n\n- `a%` an any block.\n- `1a%` an open-to-close block.  Includes mids but does not include open\n  and close words.\n- `{count}a%` if `{count}` is greater than 1, the `{count}`th surrounding\n  open-to-close block.\n\nSee [here](#line-wise-operatortext-object-combinations)\nfor some examples and important special cases.\n\n#### (c.1) highlight `()`, `[]`, and `{}`\n\nmatch-up emulates vim's matchparen to highlight the symbols contained\nin the `matchpairs` setting.\n\n#### (c.2) highlight _all_ matches\n\nTo disable match highlighting at startup, use\n`let g:matchup_matchparen_enabled = 0`\nin your vimrc.\nSee [here](#module-matchparen) for more information and related\noptions.\n\nYou can enable highlighting on the fly using `:DoMatchParen`.\nLikewise, you can disable highlighting at any time using\n`:NoMatchParen`.\n\nAfter start-up, is better to use `:NoMatchParen` and `:DoMatchParen`\nto toggle highlighting globally than setting the global variable\nsince these commands make sure not to leave stale matches around.\n\n#### (c.3) display matches off screen\n\nIf a open or close which would have been highlighted is on a line\npositioned outside the current window, the match is shown in the\nstatus line or popup window.\nIf both the open and close match are off-screen, the\nclose match is preferred.\nSee the option `g:matchup_matchparen_offscreen` for more details.\n\nFor popup style (supported in recent vim and neovim versions):\n\n```vim\nlet g:matchup_matchparen_offscreen = {'method': 'popup'}\n```\n\nFor status line style (default):\n\n```vim\nlet g:matchup_matchparen_offscreen = {'method': 'status'}\n```\n\n#### (c.4) where am I?\n\nIf you are lost, you can ask match-up where you are using\n\n    :MatchupWhereAmI?\n\nThis echos your position in the code in a breadcrumb-style by finding\nsuccessive matching words, like doing `[%` repeatedly.\n\nIt's useful to bind this to a key (not bound by default)\n\n```vim\nnnoremap \u003cc-k\u003e :\u003cc-u\u003eMatchupWhereAmI?\u003ccr\u003e\n```\n\nIf you are really lost, you can ask a bit harder to get a more detailed\nprint out.\n\n    :MatchupWhereAmI??\n\n### Inclusive and exclusive motions\n\nIn vim, character motions following operators (such as `d` for delete\nand `c` for change) are either [inclusive] or [exclusive].  This means\nthey either include the ending position or not.  Here, \"ending position\"\nmeans the line and column closest to the end of the buffer of the region\nswept over by the motion.  match-up is designed so that `d]%` inside a set\nof parenthesis behaves exactly like `d])`, except generalized to words.\n\nPut differently, _forward_ exclusive motions will not include the close\nword.  In this example, where `█` is the cursor position,\n\n```vim\nif █x | continue | endif\n```\n\npressing `d]%` will produce (cursor on the `e`)\n\n```vim\nif endif\n```\n\nTo include the close word, use either `dv]%` or `v]%d`.  This is also\ncompatible with vim's `d])` and `d]}`.\n\nOperators over _backward_ exclusive motions will instead exclude the\nposition the cursor was on before the operator was invoked.  For example,\nin\n\n```vim\n  if █x | continue | endif\n```\npressing `d[%` will produce\n\n```vim\n  █x | continue | endif\n```\nThis is compatible with vim's `d[(` and `d[{`.\n\nUnlike `]%`, `%` is an [inclusive] motion.  As a special case for the\n`d` (delete) operator, if `d%` leaves behind lines white-space, they will\nbe deleted also.  In effect, it will be operating line-wise.  As an\nexample, pressing `d%` will leave behind nothing.\n\n```text\n   █(\n\n   )\n```\n\nTo operate character-wise in this situation, use `dv%` or `v%d`.\nThis is vim compatible with the built-in `d%` on `matchpairs`.\n\n### Line-wise operator/text-object combinations\n\nNormally, the text objects `i%` and `a%` work character-wise.  However,\nthere are some special cases.  For certain operators combined with `i%`,\nunder certain conditions, match-up will effectively operate line-wise\ninstead.  For example, in\n```vim\nif condition\n █call one()\n  call two()\nendif\n```\npressing `di%` will produce\n```vim\nif condition\nendif\n```\neven though deleting ` condition` would be suggested by the object `i%`.\nThe intention is to make operators more useful in some cases.  The\nfollowing rules apply:\n1. The operator must be listed in `g:matchup_text_obj_linewise_operators`.\n  By default this is `d` and `y` (e.g., `di%` and `ya%`).\n2. The outer block must span multiple lines.\n3. The open and close delimiters must be more than one character long.  In\n  particular, `di%` involving a `(`...`)` block will not be subject to\n  these special rules.\n\nTo prevent this behavior for a particular operation, use `vi%d`.  Note that\nspecial cases involving indentation still apply (like with |i)| etc).\n\nTo disable this entirely, remove the operator from the following variable,\n```vim\nlet g:matchup_text_obj_linewise_operators = [ 'y' ]\n```\n\nNote: unlike vim's built-in `i)`, `ab`, etc., `i%` does not make an\nexisting visual mode character-wise.\n\nA second special case involves `da%`.  In this example,\n```vim\n    if condition\n     █call one()\n      call two()\n    endif\n```\npressing `da%` will delete all four lines and leave no white-space.  This\nis vim compatible with `da(`, `dab`, etc.\n\n## Options\n\nTo disable the plugin entirely,\n```vim\nlet g:matchup_enabled = 0\n```\ndefault: 1\n\nTo disable a particular module,\n```vim\nlet g:matchup_matchparen_enabled = 0\nlet g:matchup_motion_enabled = 0\nlet g:matchup_text_obj_enabled = 0\n```\ndefaults: 1\n\nTo enable the delete surrounding (`ds%`) and change surrounding (`cs%`)\nmaps,\n```vim\nlet g:matchup_surround_enabled = 1\n```\ndefault: 0\n\nTo enable the experimental\n[transmute](https://github.com/andymass/vim-matchup/blob/5a1978e46a0e721b5c5d113379c685ff7ec339e7/doc/matchup.txt#L311)\nmodule,\n```vim\nlet g:matchup_transmute_enabled = 1\n```\ndefault: 0\n\nTo configure the number of lines to search in either direction while using\nmotions and text objects.  Does not apply to match highlighting\n(see `g:matchup_matchparen_stopline` instead).\n```vim\nlet g:matchup_delim_stopline = 1500\n```\ndefault: 1500\n\nTo disable matching within strings and comments,\n```vim\nlet g:matchup_delim_noskips = 1   \" recognize symbols within comments\nlet g:matchup_delim_noskips = 2   \" don't recognize anything in comments\n```\ndefault: 0 (matching is enabled within strings and comments)\n\n### Variables\n\nmatch-up understands the following variables from matchit.\n- `b:match_words`\n- `b:match_skip`\n- `b:match_ignorecase`\n\nThese are set in the respective ftplugin files.  They may not exist for\nevery file type.  To support a new file type, create a file\n`after/ftplugin/{filetype}.vim` which sets them appropriately.\n\n### Module matchparen\n\nTo disable match highlighting at startup, use\n`let g:matchup_matchparen_enabled = 0` in your vimrc.\nNote: vim's built-in plugin |pi_paren| plugin is also disabled.\nThe variable `g:loaded_matchparen` has no effect on match-up.\n\n#### Customizing the highlighting colors\n\nmatch-up uses the `MatchParen` highlighting group by default, which can be\nconfigured.  For example,\n```vim\n:hi MatchParen ctermbg=blue guibg=lightblue cterm=italic gui=italic\n```\n\nYou may want to put this inside a `ColorScheme` `autocmd` so it is\npreserved after colorscheme changes:\n```vim\naugroup matchup_matchparen_highlight\n  autocmd!\n  autocmd ColorScheme * hi MatchParen guifg=red\naugroup END\n```\n\nYou can also highlight words differently than parentheses using the\n`MatchWord` highlighting group.  You might do this if you find the\n`MatchParen` style distracting for large blocks.\n```vim\n:hi MatchWord ctermfg=red guifg=blue cterm=underline gui=underline\n```\n\nThere are also `MatchParenCur` and `MatchWordCur` which allow you to\nconfigure the highlight separately for the match under the cursor.\n```vim\n:hi MatchParenCur cterm=underline gui=underline\n:hi MatchWordCur cterm=underline gui=underline\n```\n\nThe matchparen module can be disabled on a per-buffer basis (there is\nno command for this).  By default, when disabling highlighting for a\nparticular buffer, the standard plugin matchparen will still be used\nfor that buffer.\n\n```vim\nlet b:matchup_matchparen_enabled = 0\n```\ndefault: 1\n\nIf this module is disabled on a particular buffer, match-up will still\nfall-back to the vim standard plugin matchparen, which will highlight\n`matchpairs` such as `()`, `[]`, \u0026 `{}`.  To disable this,\n```vim\nlet b:matchup_matchparen_fallback = 0\n```\ndefault: 1\n\nA common usage of these options is to automatically disable\nmatchparen for particular file types;\n```vim\naugroup matchup_matchparen_disable_ft\n  autocmd!\n  autocmd FileType tex let [b:matchup_matchparen_fallback,\n      \\ b:matchup_matchparen_enabled] = [0, 0]\naugroup END\n```\n\nWhether to highlight known words even if there is no match:\n```vim\nlet g:matchup_matchparen_singleton = 1\n```\ndefault: 0\n\nDictionary controlling the behavior with off-screen matches.\n```vim\nlet g:matchup_matchparen_offscreen = { ... }\n```\n\ndefault: `{'method': 'status'}`\n\nIf empty, this feature is disabled.  Else, it should contain the\nfollowing optional keys:\n\n- `method`:\n  Sets the method to use to show off-screen matches.\n  Possible values are:\n\n  `'status'` (default): Replace the _status-line_ for off-screen matches.\n\n  If a match is off of the screen, the line belonging to that match will be\n  displayed syntax-highlighted in the status line along with the line number\n  (if line numbers are enabled).  If the match is above the screen border,\n  an additional Δ symbol will be shown to indicate that the matching line is\n  really above the cursor line.\n\n  `'popup'`: Show off-screen matches in a popup (vim) or\n  floating (neovim) window.\n\n  `'status_manual'`: Compute the string which would be displayed in the\n  status-line or popup, but do not display it.  The function\n  `MatchupStatusOffscreen()` can be used to get the text.\n\n- `scrolloff`:\n  When enabled, off-screen matches will not be shown in the statusline while\n  the cursor is at the screen edge (respects the value of 'scrolloff').\n  This is intended to prevent flickering while scrolling with j and k.\n\n  default: 0.\n\nThe number of lines to search in either direction while highlighting\nmatches.  Set this conservatively since high values may cause performance\nissues.\n```vim\nlet g:matchup_matchparen_stopline = 400  \" for match highlighting only\n```\n\ndefault: 400\n\n#### highlighting timeouts\n\nAdjust timeouts in milliseconds for matchparen highlighting:\n```vim\nlet g:matchup_matchparen_timeout = 300\nlet g:matchup_matchparen_insert_timeout = 60\n```\ndefault: 300, 60\n\n#### deferred highlighting\n\nDeferred highlighting improves cursor movement performance (for example,\nwhen using `hjkl`) by delaying highlighting for a short time and waiting\nto see if the cursor continues moving;\n```vim\nlet g:matchup_matchparen_deferred = 1\n```\ndefault: 0 (disabled)\n\nNote: this feature is only available if your vim version has `timers` and\nthe function `timer_pause`, version 7.4.2180 and after.\n\nAdjust delays in milliseconds for deferred highlighting:\n```vim\nlet g:matchup_matchparen_deferred_show_delay = 50\nlet g:matchup_matchparen_deferred_hide_delay = 700\n```\ndefault: 50, 700\n\nNote: these delays cannot be changed dynamically and should be configured\nbefore the plugin loads (e.g., in your vimrc).\n\n#### highlight surrounding\n\nTo highlight the surrounding delimiters until the cursor moves, use a map\nsuch as the following\n```vim\nnmap \u003csilent\u003e \u003cF7\u003e \u003cplug\u003e(matchup-hi-surround)\n```\nThere is no default map for this feature.\n\nYou can also highlight surrounding delimiters always as the cursor moves.\n```vim\nlet g:matchup_matchparen_deferred = 1\nlet g:matchup_matchparen_hi_surround_always = 1\n```\ndefault: 0 (off)\n\nThis can be set on a per-buffer basis:\n```vim\nautocmd FileType tex let b:matchup_matchparen_hi_surround_always = 1\n```\n\nNote: this feature _requires_\n[deferred highlighting](#deferred-highlighting) to be supported and\nenabled.\n\n### Module motion\n\nIn vim, `{count}%` goes to the `{count}` percentage in the file.\nmatch-up overrides this motion for small `{count}` (by default, anything\nless than 7).  To allow `{count}%` for `{count}` less than 12,\n```vim\ng:matchup_motion_override_Npercent = 11\n```\nTo disable this feature, and restore vim's default `{count}%`,\n```vim\ng:matchup_motion_override_Npercent = 0\n```\nTo always enable this feature, use any value greater than 99,\n```vim\ng:matchup_motion_override_Npercent = 100\n```\ndefault: 6\n\nIf enabled, cursor will land on the end of mid and close words while\nmoving downwards (`%`/`]%`).  While moving upwards (`g%`, `[%`) the cursor\nwill land on the beginning.  To disable,\n```vim\nlet g:matchup_motion_cursor_end = 0\n```\ndefault: 1\n\n### Module text_obj\n\nModify the set of operators which may operate\n[line-wise](#line-wise-operatortext-object-combinations)\n```vim\nlet g:matchup_text_obj_linewise_operators = ['d', 'y']\n```\ndefault: `['d', 'y']`\n\n## FAQ\n\n- match-up doesn't work\n\n  This plugin requires at least vim 7.4.  It should work in vim 7.4.898\n  but at least vim 7.4.1689 is better.  I recommend using the most recent\n  version of vim if possible.\n\n  If you have issues, please tell me your vim version and error messages.\n  Try updating vim and see if the problem persists.\n\n- Why does jumping not work for construct X in language Y?\n\n  You can configure custom match expressions for a file type using\n\n  ```vim\n  autocmd FileType myft let b:match_words = 'something:else'`\n  ```\n\n  For more information about how to customize matching, see\n  [the wiki](https://github.com/andymass/vim-matchup/wiki/The-match-up-wiki).\n\n  For help, please open a new issue and be as specific as possible.\n\n- Highlighting is not correct for construct X\n\n  match-up uses matchit's filetype-specific data, which may not give\n  enough information to create proper highlights.  To fix this, you may\n  need to modify `b:match_words` in your configuration.\n\n  For more help, please open a new issue and be as specific as possible.\n\n- I'm having performance problems\n\n  match-up aims to be as fast as possible, but highlighting matching words\n  can be intensive and may be slow on less powerful machines.  There are a\n  few things you can try to improve performance:\n\n  1. Update to a recent version of vim.  Newer versions are faster, more\n  extensively tested, and better supported by match-up.\n  2. Try [deferred highlighting](#deferred-highlighting), which delays\n  highlighting until the cursor is stationary to improve cursor movement\n  performance.\n  3. Lower the [highlighting timeouts](#highlighting-timeouts).  Note that\n  if highlighting takes longer than the timeout, highlighting will not be\n  attempted again until the cursor moves.\n\n  If are having any other performance issues, please open a new issue and\n  report the output of `:MatchupShowTimes`.\n\n- Why is there a weird entry on the status line?\n\n  This is a feature which helps you see matches that are outside of the\n  vim screen, similar to some IDEs.  If you wish to disable it, use\n\n  ```vim\n  let g:matchup_matchparen_offscreen = {}\n  ```\n\n- Matching does not work when lines are too far apart.\n\n  The number of search lines is limited for performance reasons.  You may\n  increase the limits with the following options:\n\n  ```vim\n  let g:matchup_delim_stopline      = 1500 \" generally\n  let g:matchup_matchparen_stopline = 400  \" for match highlighting only\n  ```\n- The maps `1i%` and `1a%` are difficult to press.\n\n  You may use the following maps `I%` and `A%` for convenience:\n\n  ```vim\n  function! s:matchup_convenience_maps()\n    xnoremap \u003csid\u003e(std-I) I\n    xnoremap \u003csid\u003e(std-A) A\n    xmap \u003cexpr\u003e I mode()=='\u003cc-v\u003e'?'\u003csid\u003e(std-I)':(v:count?'':'1').'i'\n    xmap \u003cexpr\u003e A mode()=='\u003cc-v\u003e'?'\u003csid\u003e(std-A)':(v:count?'':'1').'a'\n    for l:v in ['', 'v', 'V', '\u003cc-v\u003e']\n      execute 'omap \u003cexpr\u003e' l:v.'I%' \"(v:count?'':'1').'\".l:v.\"i%'\"\n      execute 'omap \u003cexpr\u003e' l:v.'A%' \"(v:count?'':'1').'\".l:v.\"a%'\"\n    endfor\n  endfunction\n  call s:matchup_convenience_maps()\n  ```\n\n  Note: this is not compatible with the plugin targets.vim.\n\n- How can I contribute?\n\n  Read the [contribution guidelines](CONTRIBUTING.md) and [issue\n  template](.github/ISSUE_TEMPLATE/bug_report.md).  Be as precise and\n  detailed as possible\n  when submitting issues and pull requests.\n\n## Interoperability\n\n### vimtex, for LaTeX documents\n\nBy default, match-up will be disabled automatically for tex files when\n[vimtex] is detected.  To enable match-up for tex files, use\n\n```vim\nlet g:matchup_override_vimtex = 1\n```\n\nmatch-up's matching engine is more advanced than vimtex's and supports\nmiddle delimiters such as `\\middle|` and `\\else`.  The exact set of\ndelimiters recognized may differ between the two plugins.  For example,\nthe mappings `da%` and `dad` will not always match, particularly if you\nhave customized vimtex's delimiters.\n\n### Surroundings\n\nmatch-up provides built-in support for [vim-surround]-style `ds%` and\n`cs%` operations (`let g:matchup_surround_enabled = 1`).\nIf vim-surround is installed, you can use vim-surround\nreplacements such as `cs%)`.  `%` cannot be used as a replacement.\nAn alternative plugin is [vim-sandwich], which allows more complex\nsurround replacement rules but is not currently supported.\n\n[vim-surround]: https://github.com/tpope/vim-surround\n[vim-sandwich]: https://github.com/machakann/vim-sandwich\n\n### Auto-closing plugins\n\nmatch-up does not provide auto-complete or auto-insertion of matches.\nSee for instance one of the following plugins for this;\n\n- [vim-endwise](https://github.com/tpope/vim-endwise)\n- [auto-pairs](https://github.com/jiangmiao/auto-pairs)\n- [delimitMate](https://github.com/Raimondi/delimitMate)\n- [splitjoin.vim](https://github.com/AndrewRadev/splitjoin.vim)\n- [Pear Tree](https://github.com/tmsvg/pear-tree)\n\n### Matchit\n\nmatch-up tries to work around matchit.vim in all cases, but if\nyou experience problems, read the following:\n\n- For vim, matchit.vim should not be loaded.  If it is loaded, it should\n  be loaded after match-up (in this case, matchit.vim will be disabled).\n  Note that some plugins, such as\n  [vim-sensible](https://github.com/tpope/vim-sensible), load matchit.vim\n  so these should also be initialized after match-up.\n\n- For neovim, matchit.vim is loaded by default.  This should not cause any\n  problems, but you may see a very slight start-up time improvement by\n  setting `let g:loaded_matchit = 1` in your `init.vim`.\n\n### Matchparen emulation\n\nmatch-up loads [matchparen] if it is not already loaded.  Ordinarily, match-up\ndisables matchparen's highlighting and emulates it to highlight the symbol\ncontained in the 'matchpairs' option (by default `()`, `[]`, and `{}`).  If match-up\nis disabled per-buffer using `b:matchup_matchparen_enabled`, match-up will use\nmatchparen instead of its own highlighting.  See `b:matchup_matchparen_fallback`\nfor more information.\n\n## Acknowledgments\n\n### Origins\n\nmatch-up was originally based on [@lervag](https://github.com/lervag)'s\n[vimtex].  The concept and style of this plugin and its development are\nheavily influenced by vimtex. :beers:\n\n[vimtex]: https://github.com/lervag/vimtex\n\n### Other inspirations\n\n- [matchit](http://ftp.vim.org/pub/vim/runtime/macros/matchit.txt)\n- [matchparen](http://ftp.vim.org/pub/vim/runtime/doc/pi_paren.txt)\n- [MatchTag](https://github.com/gregsexton/MatchTag)\n- [MatchTagAlways](https://github.com/Valloric/MatchTagAlways)\n- [vim-textobj-anyblock](https://github.com/rhysd/vim-textobj-anyblock)\n\n## Development\n\n### Reporting problems\n\nThorough issue reports are encouraged.  Please read the [issue\ntemplate](.github/ISSUE_TEMPLATE/bug_report.md) first.  Be as precise and\ndetailed as\npossible when submitting issues.\n\nFeature requests are also welcome.\n\n### Contributing\n\nPlease read the [contribution guidelines](CONTRIBUTING.md) before\ncontributing.\n\nContributions are welcome!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandymass%2Fvim-matchup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandymass%2Fvim-matchup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandymass%2Fvim-matchup/lists"}