Library / SDK
sublimehq/Packages avatar
sublimehq/Packages

Sublime Packages: Build 4095 is the floor, and an empty zip is how you override a shipped package

Syntax highlighting files shipped with Sublime Text and Sublime Merge

3,023 stars594 forksShellNOASSERTION

At a glance

What is it?
This repository holds the syntax definitions that ship inside Sublime Text and Sublime Merge, and its documentation is aimed at people changing them rather than installing them. What it spells out in unusual detail is the override mechanic: symlinking a package over the shipped one merges rather than replaces, so files you deleted keep coming back, and the documented cure is an empty zip archive placed in the installed packages folder so the editor loads nothing where it used to load a package.
Who is it for?
This repository is for editing the syntax definitions that ship with the editor, not for extending it, and the documentation is precise enough that a contributor could work from it alone. Three things to check before you start.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 8 days ago.
What is it written in?
Mainly Shell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • sublimehq/Packages3,023 ★ · +7
Star history
Repository2026-09-252026-11-15
sublimehq/Packages3k3k

7 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Build 4095 is a hard floor, and development targets the dev channel

The requirements section is three sentences and the third one is the constraint that matters. These packages are developed against the latest build of Sublime Text in the dev channel, so the working target is the newest build rather than the current release. The latest release of the packages shipped with the editor is supposed to be tagged in this repository, and the tag list is the place to see them, which is why the repository itself publishes no GitHub releases. Then the caveat: bugs may exist on older builds, and the format used is not compatible with builds older than Build 4095. That is a hard floor rather than a deprecation warning, so a contributor working against an older editor is not working against a degraded experience, they are working against an incompatible format.

Three symlink commands and one junction, because Windows symlinks need rights

The local test recipe is the same on every platform: fork the repository, clone it, then symlink the directory of the package you changed into the editor's packages folder, replacing the name Python in the commands with the syntax you are working on. On macOS the target is inside Application Support with the spaces escaped, on Linux it is a config directory with a hyphenated folder name, and on Windows the page steers you away from symlinks entirely because they require administrative rights. The Windows command creates a directory junction instead, so the clone and the junction run from a PowerShell prompt, with a path conversion helper for the source. There is a fourth route for Windows that avoids both: download the portable version of the editor and clone the repository directly as a subdirectory of its data folder.

Overriding a package does not delete what the editor shipped

The section on what to keep in mind is the reason most people arrive here. Once a symlink is in place you are overriding a default package, which brings two consequences. The first is maintenance: if other people make upstream changes to a package you have overridden, your copy goes out of date the moment the editor updates, and the fix is to pull from this repository. The second is the one that wastes an afternoon. If you delete or rename files, but those files still exist in the shipped version of the package, the originals keep being picked up. Moving a syntax test into a tests subfolder and running the tests still leaves the old file loaded as well as the new one, and no amount of deleting from your side will change that.

An empty zip is the documented way to replace rather than merge

The page solves that with a trick worth reading closely. To stop the shipped package loading at all, you create an empty zip archive named like the package, for example as an SQL package file, in the editor's Installed Packages directory, and that causes the editor to load your empty package in place of the one that shipped. The net effect, as the page puts it, is that you are overriding an empty package instead of merging new files into an existing one. Two ways of producing the file are given: a printf that writes out the bytes of an archive containing no entries, and a sequence that zips a placeholder file and then deletes the entry from the archive:

bash
printf "PK\x05\x06\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" > empty.zip
# or
touch dummy && zip empty.zip dummy && zip -d empty.zip dummy && rm dummy

You can also make the placeholders visible in a directory listing by symlinking the empty archive to the package name rather than copying it.

New language packages are refused, and the reason is name collisions

One part of the contribution guide is a flat refusal. Pull requests for new packages are not accepted at this stage, and the reason is user-facing rather than aesthetic: a new package can cause problems for users who already have a package with the same name installed through Package Control. The page says there are planned changes that will address this later, so the policy is understood to be temporary. A related norm follows from the same reasoning: complex plugins, with auto-complete systems and linters named as examples, should generally go in a standalone package rather than into the default set. So the scope of this repository is deliberately narrow, and a proposal that ignores that gets closed on the grounds of the policy rather than on its merit.

A pull request needs a bracketed name, a syntax test and performance numbers

The five requirements for a change are worth reading as a checklist for a contributor. The title starts with the package name in square brackets, with XML given as the example. The change should be as small and self-contained as is reasonable, on the stated grounds that smaller changes are quicker to review. A new or enhanced syntax test is required when a syntax definition file changes. For a significant change the bar rises twice: multiple syntax tests and a set of performance measurements comparing the old version with the new one. And the commit history stays linear because changes are squashed on merge. So a large rewrite needs both correctness evidence and a timing comparison before it will be considered.

Fifty syntax directories, named for display rather than for scripts

The tree is the fastest way to see the scope. There are around fifty directories, each a language or format, ranging from the obvious ones such as Python, Ruby, Rust, Go and Java to format-specific entries such as Diff, Text, Textile, Makefile, Graphviz and Git Formats. Two things follow from the naming. The directory names are display names rather than identifiers, with spaces and punctuation in them, including a hash in the C sharp and C plus plus names and a hyphen in the shell script name, so any script that iterates the tree has to handle quoting. And the set is explicitly incomplete: the page states that the repository holds only syntax-definition-focused packages and names Default and Theme - Default as notably absent, which is a useful thing to know before looking for the colour scheme.

Editorial conclusion

This repository is for editing the syntax definitions that ship with the editor, not for extending it, and the documentation is precise enough that a contributor could work from it alone. Three things to check before you start. Which build you are targeting, since the format is not compatible with anything older than Build 4095 and the work is developed against the dev channel, so an older editor in your setup will not read what you write. Whether you are merging or replacing, because a symlinked package merges with the shipped one and your deletions will be undone by the next editor update unless you drop an empty zip into the installed packages folder. And what you are allowed to add, since new language packages are refused at this stage over Package Control name collisions, and anything resembling a plugin is expected to live in a standalone package instead.

Frequently asked questions

How do I test a syntax change in sublimehq/Packages?

Fork the repository, clone it, and symlink the directory of the package you changed into the editor's packages folder, replacing Python in the commands with the syntax name. On macOS the target is under Application Support, on Linux under a config directory, and on Windows the page uses a directory junction created with mklink because symlinks need administrative rights there. The portable editor can also be used by cloning the repository as a subdirectory of its data folder.

Why does a file I deleted still get loaded in Sublime Text?

Because the shipped package still contains it. Deleting or renaming files in an overriding package does not remove the originals, so they keep being picked up alongside your versions. The page's fix is to create an empty zip archive named like the package, for example an SQL package file, in the editor's Installed Packages directory, which makes it load that empty package in place of the shipped one instead of merging into it.

What does a pull request to sublimehq/Packages have to include?

A title starting with the package name in square brackets such as [XML], a change as small and self-contained as reasonable, a new or enhanced syntax test when a syntax definition file changes, and for a significant change both multiple syntax tests and performance measurements comparing the old and new versions. Changes are squashed on merge to keep the history linear.

Can I add a new language package to sublimehq/Packages?

Not at this stage. The page says pull requests for new packages are not accepted because a new package can cause issues for users who already have one with the same name installed through Package Control, and that planned changes will address this later. Complex plugins such as auto-complete systems and linters are expected to live in a standalone package rather than the default set.

Official sources

  1. Issues
  2. Project website
  3. README
  4. sublimehq/Packages on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sublimehq-packages.svg)](https://hysenlabs.com/projects/sublimehq-packages)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sublimehq-packages.svg)](https://hysenlabs.com/projects/sublimehq-packages)

Was this useful?