Sublime Forum

How should customizations be organized?

#1

Where should I put all of my custom snippets, preferences and packages that I maintain manually (outside of package control)? Is there a tutorial on how the Sublime Text 3 Application Support directory should be organized?

1 Like
#2

As far as I’m aware, there’s no direct tutorial on how you would organize things. Note however:

  1. All customizations should live inside of a Package
  2. Packages should either be folders in the Packages folder or sublime-package files in the Installed Packages folder
  3. Plugin files have to be in the top level of a package or Sublime won’t load them; other resources can exist anywhere inside a package

Within these constraints, you’re free to do whatever you want, layout-wise. So I would say, whatever works best for you is probably a good way to go.

I think generally people put their customizations somewhere inside their User package; that ensures that no matter what other packages might be installed, your custom additions “win” by being loaded last.

You can create as many folders and sub-folders as you want inside the User package (or any package) to keep things neatly organized and easy to find. The only thing you have to keep in mind is #3 above; plugins have to be top level (or you need to do more work to get Sublime to load them).

2 Likes
#3

I noticed a lot of the default packages located under Packages folder while they also exist under Cache. Are these possibly duplicates? One reason I ask this is because updating to the latest version does not provide me with the right default theme; it’s the old default theme rather than the updated one I see from the blog.

0 Likes
#4

There are three places where packages can live:

  • In a folder named Packages that is stored alongside the Sublime Text binary (i.e. at the install location). Packages here are stored as sublime-package files and they’re the default packages that Ship with Sublime. You shouldn’t fiddle with them unless you know what you’re doing because they will be replaced wholesale when Sublime updates or is reinstalled.

  • In a folder named Installed Packages; packages here are also installed as sublime-package files, but they’re the packages that you installed yourself. Package Control puts most packages that it installs here, but you’re also free to create your own sublime-package files and drop them here if you want. As above, you don’t want to fiddle with sublime-package files that Package Control installed because it will replace them wholesale when it upgrades packages.

  • In a folder named Packages; In this folder, packages are represented as folders that contain files instead of sublime-package files. Your User package lives here, and Package Control will install packages here if the package author has specified that their package should be installed this way (that is, instead of as a sublime-package file in the above folder). Additionally, package dependencies are installed here as well (they generally have names that are all lower case, though that’s just a convention and not a rule).

Since it’s not a good idea to modify a sublime-package file (which is just a zip file with the extension changed), Sublime supports the idea of an override, which allows you to modify a package in a way that won’t get lost.

To do that, you create a folder in the Packages folder that has the same name as the sublime-package you want to modify, and inside of that folder put a copy of the file that you want to modify. When Sublime loads packages, any time it finds a file with an identical name inside of the sublime-package file AND in the Packages folder, it will load the unpacked version of the file instead. That way if/when the sublime-package gets modified, your change is not lost.

All of this is a long winded way of saying that it’s not uncommon for the Packages folder to contain only your User package and it’s not uncommon for the Packages folder to contain a whole bunch of folders if you have overrides or just happen to install the sorts of packages that install that way.

You shouldn’t concern yourself with the Cache folder at all; that’s where Sublime stores temporary cache files. In addition packages may sometimes also store files in that location as well. The contents of the cache folder is meant to be temporary in the sense that if the files are removed, nothing breaks and they will be recreated.

An example would be that when a brand new syntax definition is encountered, it has to be “compiled” into an in-memory format to allow it to be used. Sublime caches the results of that compilation there and reuses the files there if they exist (or creates them again if not).

This problem sounds like it might be a consequence of having overrides (as outlined above). When you override a package file, Sublime uses the override unconditionally and ignores the packaged version, even if the package is upgraded.

The result of that would be that if you happen to have an override on the theme file, even though the package has been updated, your override is still in effect and effectively masking the changes.

The PackageResourceViewer package is often used to look at package files or create overrides, but due to the way that it works people sometimes inadvertently create an override even if they didn’t mean to. It also contains a command that will extract an entire package all at once, which has the effect of overriding the entire package all at once.

The OverrideAudit package (disclaimer: I’m the author) is designed to warn you when this sort of thing is happening. It allows you to see what overrides you have in place, compare them to the underlying file to see how they’re different, and remove them if you don’t want them any longer.

It will also warn you if you have an override that is “expired” or “out of date” (based on the packaged version being newer than the override) to let you know that the underlying file may have changed. There is an intro video that gives you an overview of how it works, plus full documentation.

0 Likes
#5

First of all, thank you so much for you’re detailed explanations at to how this all works. Very enlightening and very much appreciated.

Here’s my OverrideAudit report:

WARNING: Showing only expired overrides!
WARNING: Non-expired overrides may exist!

Report Generated: 2019-04-09 16:40:42

[S U] C++
  `- [X] C++.sublime-settings
  `- [X] Comments (C++).tmPreferences
  `- [X] Completion Rules.tmPreferences
  `- [X] Indentation Rules.tmPreferences
  `- [X] Symbol List - Indent Class Methods.tmPreferences
  `- [X] Symbol List - Prefix Banner Items.tmPreferences

[S U] CSS
  `- [X] Comments.tmPreferences
  `- [X] Symbol List Group.tmPreferences
  `- [X] Symbol List.tmPreferences
  `- [X] css_completions.py

[S U] Clojure
  `- [X] Comment.tmPreferences

[S U] D
  `- [X] Comments.tmPreferences
  `- [X] D.sublime-build
  `- [X] Indentation Rules.tmPreferences

[S U] Diff
  `- [X] Context.sublime-menu
  `- [X] Side Bar.sublime-menu
  `- [X] diff.py

[S U] Erlang
  `- [X] Comments.tmPreferences
  `- [X] Erlang.sublime-build
  `- [X] Function Symbols.tmPreferences
  `- [X] Indentation Rules.tmPreferences
  `- [X] Macro Symbols.tmPreferences
  `- [X] Module Symbols.tmPreferences
  `- [X] Record Symbols.tmPreferences
  `- [X] Symbol Overrides.tmPreferences

[S U] Groovy
  `- [X] Symbol List%3A Class Variables.tmPreferences
  `- [X] Symbol List%3A Classes.tmPreferences
  `- [X] Symbol List%3A Methods.tmPreferences
  `- [X] Symbol List%3A Variables.tmPreferences

[S U] HTML
  `- [X] Comments.tmPreferences
  `- [X] Miscellaneous.tmPreferences
  `- [X] Symbol List - ID.tmPreferences
  `- [X] encode_html_entities.py
  `- [X] html_completions.py

[S U] Haskell
  `- [X] Comments.tmPreferences
  `- [X] Haskell.sublime-build
  `- [X] Indent Patterns.tmPreferences
  `- [X] Symbol List.tmPreferences

[S U] Java
  `- [X] Ant.sublime-build
  `- [X] Comments.tmPreferences
  `- [X] Completion Rules.tmPreferences
  `- [X] Indentation Rules Annex.tmPreferences
  `- [X] Indentation Rules.tmPreferences
  `- [X] JavaC.sublime-build
  `- [X] Symbol List%3A Classes.tmPreferences
  `- [X] Symbol List%3A Inner Class Methods.tmPreferences
  `- [X] Symbol List%3A Inner Classes.tmPreferences
  `- [X] Symbol List%3A Inner Inner Class Methods.tmPreferences
  `- [X] Symbol List%3A Inner Inner Classes.tmPreferences
  `- [X] Symbol List%3A Method.tmPreferences

[S U] JavaScript
  `- [X] Comments.tmPreferences
  `- [X] Completion Rules.tmPreferences
  `- [X] JavaScript Indent.tmPreferences
  `- [X] Symbol List Banned.tmPreferences
  `- [X] Symbol List Function.tmPreferences

[S U] LaTeX
  `- [X] Comments.tmPreferences

[S U] Language - English
  `- [X] README_en_GB.txt
  `- [X] README_en_US.txt
  `- [X] en_GB.aff
  `- [X] en_GB.dic
  `- [X] en_US.aff
  `- [X] en_US.dic

[S U] Lisp
  `- [X] Comments.tmPreferences

[S U] Lua
  `- [X] Comments.tmPreferences
  `- [X] Indent.tmPreferences

[S U] Makefile
  `- [X] Make.sublime-build
  `- [X] Makefile.sublime-settings
  `- [X] Miscellaneous.tmPreferences

[S U] Markdown
  `- [X] Indent%3A Raw.tmPreferences
  `- [X] Symbol List - Heading.tmPreferences

[S U] Matlab
  `- [X] Indent.tmPreferences
  `- [X] Miscellaneous.tmPreferences
  `- [X] Symbols.tmPreferences

[S U] OCaml
  `- [X] Indent rules.tmPreferences
  `- [X] Miscellaneous.tmPreferences
  `- [X] Symbol List%3A Classes.tmPreferences
  `- [X] Symbol List%3A Exceptions.tmPreferences
  `- [X] Symbol List%3A Ocamllex pattern definition.tmPreferences
  `- [X] Symbol List%3A Ocamllex pattern references.tmPreferences
  `- [X] Symbol List%3A Ocamllex rules.tmPreferences
  `- [X] Symbol List%3A Ocamlyacc non-terminal definition.tmPreferences
  `- [X] Symbol List%3A Ocamlyacc non-terminal reference.tmPreferences
  `- [X] Symbol List%3A Ocamlyacc token definition.tmPreferences
  `- [X] Symbol List%3A Ocamlyacc token reference.tmPreferences
  `- [X] Symbol List%3A Types.tmPreferences
  `- [X] Symbol List%3A Variants.tmPreferences
  `- [X] Symbol List_ Classes.tmPreferences
  `- [X] Symbol List_ Exceptions.tmPreferences
  `- [X] Symbol List_ Ocamllex pattern definition.tmPreferences
  `- [X] Symbol List_ Ocamllex pattern references.tmPreferences
  `- [X] Symbol List_ Ocamllex rules.tmPreferences
  `- [X] Symbol List_ Ocamlyacc non-terminal definition.tmPreferences
  `- [X] Symbol List_ Ocamlyacc non-terminal reference.tmPreferences
  `- [X] Symbol List_ Ocamlyacc token definition.tmPreferences
  `- [X] Symbol List_ Ocamlyacc token reference.tmPreferences
  `- [X] Symbol List_ Types.tmPreferences
  `- [X] Symbol List_ Variants.tmPreferences

[S U] PHP
  `- [X] Comments.tmPreferences
  `- [X] Completion Rules.tmPreferences
  `- [X] Indentation Rules Annex.tmPreferences
  `- [X] Indentation Rules.tmPreferences
  `- [X] PHP.sublime-completions
  `- [X] Symbol List.tmPreferences

[S U] Perl
  `- [X] Miscellaneous.tmPreferences

[S U] Python
  `- [X] Completion Rules.tmPreferences
  `- [X] Miscellaneous.tmPreferences
  `- [X] Python.sublime-build
  `- [X] Symbol List.tmPreferences

[S U] R
  `- [X] Comments.tmPreferences
  `- [X] Methods.tmPreferences
  `- [X] Symbol List (Rd Documentation).tmPreferences

[S U] Rails
  `- [X] Ruby Haml Comments.tmPreferences
  `- [X] Template (ERB).tmPreferences
  `- [X] Template (Haml).tmPreferences

[S U] RestructuredText
  `- [X] Comments.tmPreferences

[S U] Ruby
  `- [X] Comments.tmPreferences
  `- [X] Completion Rules.tmPreferences
  `- [X] Default.sublime-keymap
  `- [X] Miscellaneous.tmPreferences
  `- [X] Ruby.sublime-build

[S U] SQL
  `- [X] Comments.tmPreferences
  `- [X] Miscellaneous.tmPreferences

[S U] Scala
  `- [X] Comments.tmPreferences
  `- [X] Symbols.tmPreferences
  `- [X] info.plist

[S U] ShellScript
  `- [X] Comments.tmPreferences

[S U] TCL
  `- [X] Comments.tmPreferences

[S U] Text
  `- [X] Plain text.tmLanguage

[S U] Theme - Default
  `- [X] Default.sublime-theme

[S U] [Vintage]
  `- [X] Default (Linux).sublime-keymap
  `- [X] Default (OSX).sublime-keymap
  `- [X] Default (Windows).sublime-keymap
  `- [X] Default.sublime-keymap
  `- [X] Preferences (OSX).sublime-settings
  `- [X] Preferences.sublime-settings
  `- [X] README.TXT
  `- [X] Vintage.sublime-commands
  `- [X] vintage.py
  `- [X] vintage_commands.py
  `- [X] vintage_motions.py

[S U] XML
  `- [X] Comments.tmPreferences
  `- [X] Miscellaneous.tmPreferences
  `- [X] XML.sublime-settings

[S U] YAML
  `- [X] Comments.tmPreferences

What does the [S U] part declare (EDIT: Nevermind this question)? Also, would it be safe for me to clean up a lot of these overrides (where can I find the package that is being overridden)?

BIG EDIT

I went ahead and moved all packages inside of /Packages that were shipped with sublime and unpacked overrides. Now my package report for the very awesome OverrideAudit. The only ones left that are of concern to me are the ones marked [U]. I’m not sure how these are managed, but I’ll figure this out.

So should I put all of my custom snippets and customizations under /Packages/User/ and will I be safe from being replaced by reinstall/update or Package Control overrides?

0 Likes
#6

If you right click on an override or package name in the report, you can get OverrideAudit to generate a diff that shows you what’s different between the two files. Using that you could determine if you want to keep the changes or not. How you would do that depends on why you made the original changes (or at some level if they were intentional).

Your User package is the best place for your own specific additions to Sublime, such as your own custom snippets and such. Package Control will never install a package by that name, and except for storing your customized settings and other data files, packages should leave that folder alone too, so things there should be safe.

0 Likes