This guide is deprecated. New content at docs.sublimetext.info
Sublime Text uses .sublime-settings files to store configuration data. Settings control many aspects of the editor, from visual layout to file type options. The purpose of .sublime-settings files is determined by their name.
A hierarchy of .sublime-settings files controls settings specific to a file type. Therefore, the location of settings matters. As it’s always the case when merging files of any kind, Sublime Text gives the top priority to files in the User package. See the section Merging and Order of Preference for more information.
In addition, there’s yet another layer of settings that overrides the others: the session. Session data is updated as you work on a file, so if you adjust settings for a file in any way (mainly through API calls), they will be recorded in the session and will take precedence over any .sublime-settings files. Calls to obj.settings().get() always return the value in effect for obj at the time it was called.
When untangling the applicable settings for a file at any time, one must also keep in mind that Sublime Text adjusts settings automatically in some situations. For example, if auto_detect_indentation is on, the value a call to view.settings().get('tab_size') returns might appear unexpected, especially if you’ve explicitly set tab_size moments earlier.
Below, you can see the order in which Sublime Text would process a hypothetical hierarchy of settings for Python on Windows:
There are two types of global settings files affecting file types: Base File and Base File (Platform). Base File is always in effect for all platforms, whereas the second one only applies to the named platform. Multiple Base File and Base File (Platform) files can coexist.
If you want to target a specific file type in a .sublime-settings file, give it the name of the applicable syntax definition for said file type. Note you have to use the syntax definition’s file name, not a scope name. For example, if our syntax definition was called Python.tmLanguage, we’d need to call our settings file Python.sublime-settings. Settings files for specific file types usually live in packages, like Packages/Python, but there can be multiple settings files for the same file type in separate locations.
Whenever you want to persist settings, especially if they should be preserved between upgrades, place the relevant .sublime-settings file in Packages/User.