I’m trying to figure out a way to extend existing syntax highlighting in a way that can be packaged and shipped (ie., not placed under $HOME)—or whether this is possible at all.

For this specific situation I’m wanting to extend pbOptions of PKGBUILD.vim with additional options from dropped‐in "makepkg tiny" scripts. It also needs to be extended in a way that doesn’t just override the pbOptions since there might be multiple dropped-in scripts that would want to extend this.

I came across a couple of answers like How can I extend syntax highlighting with my own keywords? and Add keyword to existing syntax file without changing the original syntax file but they all seem to only concern user-defined extensions, not something that could be installed system wide or alongside additional extensions.

“Syntax loading procedure” from the Vim 9.1 reference manual also, as far as I can tell, suggests that only a single “main” syntax file is loaded with “[a]ny other user installed FileType or Syntax autocommands” loaded last. I take this to mean that only a single (system) .vim syntax file is read, though this one syntax file may itself include other syntax files.

Would it be possible by making a PKGBUILD-script.vim and including the PKGBUILD.vim in that and then use a regular expression to modify pbOptions? If it is, how do I ensure that this overrides PKGBUILD.vim as being considered the “main” syntax file? Is it possible to “stack” this so PKGBUILD-fooscript.vim and PKGBUILD-barscript.vim both get loaded without them knowing about each other?

Or is it possible to extend using some other method? Or is this not possible at all?

(This is all using a specific example, but a method that would be generally applicable would be great, if one exists.)

  • Why is it important to have your changes in the system config? For only one file, it's overkill but you could create a Vim plugin for your users. For system wide changes, either re-package Vim (depends on your OS' package manager), fork the Vim project or write a script that modifies the file. The three latter options will require steady maintenance and blow up if you make a mistake.
    – Friedrich
    Mar 4 at 14:01
  • Hi @Friedrich :) As mentioned in the question (let me know if there’s a better way to phrase it if it isn’t clear), I’m not talking about overriding Vim’s configuration, but (for the included example) about overriding part of PKGBUILD.vim which is part of pacman-contrib. It’s important to have it in the system so I can have it as part of fooscript and barscript’s source repositories and to install them the proper place during packaging of them when a user installs those packages on their system.
    – Freso
    Mar 4 at 16:22
  • 1
    The target location for your files should be clear from romainl's answer (with D. Ben Knoble's comment) and the repo of pacman-contrib contains pretty much the blueprint for packaging. I was a bit surprised to see how readily pacman devs dump their Vim configs in the system. As a package manager maintainer, I guess you're above the law.
    – Friedrich
    Mar 4 at 21:12

1 Answer 1


What does "packaged and shipped" mean to you, exactly? Packaged with what? Shipped how?

The general method would be to put the lines you want in after/syntax/PKGBUILD.vim:

syn match pbOptions /foo\|bar\|baz/ contained

which extends any existing pbOptions.

If you want to override any existing pbOptions, you can clear pbOptions before redefining it with your own patterns:

syn clear pbOptions
syn match pbOptions /foo\|bar\|baz/ contained

From there, the file can be distributed however you want, as a Vim plugin or, like that PKGBUILD.vim you linked to, as part of some package, via your system's package manager.

--- EDIT ---

How would this single file work with separate packages wanting to extend the same option?

There are two parts to this question.

The importance of sourcing order

The last script wins.

If none of the sourced scripts uses some variant of syn clear pbOptions, then all the pbOptions definitions will work together as one giant regular expression. This is the best case scenario, where everyone is being a good respectful citizen.

If any of the sourced scripts uses a variant of syn clear pbOptions, then all the pbOptions patterns defined before are ignored. This is the worst case scenario, where everyone tries to control what's going on… without really being able to.

Several packages

As pointed out in the comments, it is possible to split a given syntax into several scripts:


So it is possible to imagine the pacman-contrib package installing:


your foo package installing:


and my bar package installing:


which would all work together seemlessly.

But the proper way to do all this, no matter how you get Vim plugins, is to use the :help package feature.

Instead of installing stuff directly at the root of /usr/share/vim/vimfiles/, the pacman-contrib package should install its stuff under:


your foo package should install it under:


and my bar package should install its stuff under:


which, as long as package names are unique (which is mostly the package manager/registry's responsibility), guarantees that they will—at least—not overwrite each other.

So, in concrete terms…

  1. The people in charge of the pacman-contrib package should do the following move:

    # before
    # after
  2. You should package your syntax script so that it is installed there:


    with freso-stuff being whatever unique-ish name you want.

  3. Others should do the same.

  • In this case I’m referring to Arch Linux/pacman packages, so using a PKGBUILD file describing the packaging and using makepkg to actually take the source and manipulate it into an archive that a user can then pacman -U to install. Would after/syntax/PKGBUILD.vim be e.g. /usr/share/vim/vimfiles/after/syntax/PKGBUILD.vim? How would this single file work with separate packages wanting to extend the same option (e.g., fooscript wanting to do syn match pbOptions /foo/ contained and barscript wanting to do syn match pbOptions /bar/ contained)?
    – Freso
    Mar 4 at 16:25
  • 1
    The names on these files can contain arbitrary extra text (like PKGBUILD_myplugin.vim), so that’s how you’d handle multiples (I think you can also put them in a directory named after the ft, but I’m not sure.) As far as packaging goes, typically you’d have a plugin provides files as if they were under a runtimepath (like many plugins on GitHub; see also :help packages). Then you’d want to provide a way to install those files to somewhere in the runtimepath (if you’re packaging for a distro, somewhere in that distro’s system files, probably).
    – D. Ben Knoble
    Mar 4 at 20:07
  • @D.BenKnoble "I think you can also put them in a directory named after the ft"* - that's correct according to :help mysyntaxfile-add, last paragraph.
    – Friedrich
    Mar 4 at 21:06
  • Regarding the edit: I think the package's name is pacman-contrib with pacman being the package manager itself and -contrib containing the stuff for its development. I could be wrong, I'm only an Arch user, not a contributor. From my point of view, this answer looks pretty complete.
    – Friedrich
    Mar 5 at 7:15
  • OK, I updated the answer with the presumably correct pacman-contrib.
    – romainl
    Mar 5 at 9:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.