From 95562d03dc3ecf45e431125248d31eaf5ef81ce5 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Thu, 22 May 2025 09:03:16 -0600 Subject: [PATCH 1/8] feat: supplement list of typical Package contents - .sublime-commands after menus and before `metadata` since commands seem relatively common in Packages. - .sublime-completions before `snippets` since, according to the official documentation, a Snippet is just a Completion with more flexible (and more readable) content formatting. --- docs/guide/extensibility/packages.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guide/extensibility/packages.md b/docs/guide/extensibility/packages.md index 05f4a7d5..9eb08ede 100644 --- a/docs/guide/extensibility/packages.md +++ b/docs/guide/extensibility/packages.md @@ -72,10 +72,12 @@ Typical resources found in packages include: - key maps (`.sublime-keymap`) - macros (`.sublime-macro`) - menus (`.sublime-menu`) +- commands (`.sublime-commands`) - metadata (`.tmPreferences`) - mouse maps (`.sublime-mousemap`) - plugins (`.py`) - settings (`.sublime-settings`) +- completions (`.sublime-completions`) - snippets (`.sublime-snippet`) - syntax definitions (`.sublime-syntax`, `.tmLanguage`) - themes (`.sublime-theme`) From 82dd77ee53c506cfa4dc38b2dc0e84f0e82e1b65 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Thu, 22 May 2025 09:53:03 -0600 Subject: [PATCH 2/8] feat: use safer method to "reset" Sublime Text... ...to a freshly-installed state. This method keeps the old Data directory as a backup so that the step to do this is not considered quite as "extreme" as requiring a backup to recover lost customizations. --- docs/guide/extensibility/packages.md | 31 ++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/guide/extensibility/packages.md b/docs/guide/extensibility/packages.md index 9eb08ede..5fe55381 100644 --- a/docs/guide/extensibility/packages.md +++ b/docs/guide/extensibility/packages.md @@ -103,7 +103,7 @@ and you don't need to learn it. while others enhance Sublime Text to support common programming languages out of the box. - Examples: Default, Python, Java, C++, Markdown. + Examples: Default, Python, Java, C++, Markdown, reStructuredText. Located in `Shipped Packages`. @@ -312,11 +312,24 @@ packages and plugins. To revert Sublime Text to its default configuration and remove all your settings and configurations, -delete the [Data directory](../getting-started/basic-concepts.md#the-data-directory) -and restart the editor. -Keep in mind -that the `Installed Packages` folder will be deleted too, -so you'll lose all your installed packages. - -Always make sure to back up your data -before taking an extreme measure like this one! + +- Close Sublime Text if it is running. +- Rename the [Data directory](../getting-started/basic-concepts.md#the-data-directory) + to another name to keep it as a backup and reference about what + Packages you installed and what customizations you made. +- Re-start Sublime Text. + +This starts Sublime Text with a fresh new Data directory and +you will find that the "apparent bug" disappears. + +Keep in mind this also effectively de-installs every Package in +your `Installed Packages` folder, so you will probably want to +re-install the ones that are well-behaved. This sequence can also +allow you to detect which Package was misbehaving. + +If it was not a misbehaving Installed Package that +was causing the problem, then adding your own +customizations back in, one at a time can also help +isolate what was causing it. Use the renamed (now-backup-copy) +[Data directory](../getting-started/basic-concepts.md#the-data-directory) +as a reference. From 7bcf84a2c01cd230f2fc9d3b912a42d49f05e571 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Thu, 22 May 2025 09:58:41 -0600 Subject: [PATCH 3/8] feat: minor grammatical improvement --- docs/guide/extensibility/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/extensibility/packages.md b/docs/guide/extensibility/packages.md index 5fe55381..7708b21b 100644 --- a/docs/guide/extensibility/packages.md +++ b/docs/guide/extensibility/packages.md @@ -311,7 +311,7 @@ packages and plugins. To revert Sublime Text to its default configuration -and remove all your settings and configurations, +and remove all your settings and configurations: - Close Sublime Text if it is running. - Rename the [Data directory](../getting-started/basic-concepts.md#the-data-directory) From 4dd5106886d6ba8b508d6f320790c3f726e9b20c Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Thu, 22 May 2025 10:00:24 -0600 Subject: [PATCH 4/8] feat: clarify how new data directory gets created --- docs/guide/extensibility/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/extensibility/packages.md b/docs/guide/extensibility/packages.md index 7708b21b..0add1d5f 100644 --- a/docs/guide/extensibility/packages.md +++ b/docs/guide/extensibility/packages.md @@ -319,7 +319,7 @@ and remove all your settings and configurations: Packages you installed and what customizations you made. - Re-start Sublime Text. -This starts Sublime Text with a fresh new Data directory and +When Sublime Text starts, it will create a fresh new Data directory and you will find that the "apparent bug" disappears. Keep in mind this also effectively de-installs every Package in From 1f6028538ad99fe2d8d17871131cb62913ccfeb2 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 25 May 2025 09:19:23 -0600 Subject: [PATCH 5/8] feat: replace previous "revert" section with... ...a full troubleshooting section that includes using the new Safe Mode (since Sublime Text 4) and then continuing with the Data Directory "surgery" if the problem was not isolated/resolved up to that point. --- docs/guide/extensibility/packages.md | 86 +++++++++++++++++++++------- 1 file changed, 65 insertions(+), 21 deletions(-) diff --git a/docs/guide/extensibility/packages.md b/docs/guide/extensibility/packages.md index 0add1d5f..2f8dcf44 100644 --- a/docs/guide/extensibility/packages.md +++ b/docs/guide/extensibility/packages.md @@ -301,17 +301,44 @@ Sublime Text loads packages in this order: 1. `Packages/User` -## Reverting Sublime Text to Its Default Configuration +## Troubleshooting -Reverting Sublime Text to a fresh state -solves many problems -that appear to be bugs in Sublime Text -but are in fact caused by misbehaving -packages and plugins. +Because Sublime Text is so customizable, it is possible for 3rd-party Packages +and/or local customization to interfere with one another, or cause other problems. +You might see this, for example, seeing Python exceptions that don't make sense +in the Console Panel, or certain functionality isn't behaving as you expect. - -To revert Sublime Text to its default configuration -and remove all your settings and configurations: +### Safe Mode + +As of Sublime Text 4, you can now launch Sublime Text in Safe Mode by using + + subl --safe-mode + +from the command line to launch it. When launched this way, Sublime Text uses an +alternate [Data Directory](../getting-started/basic-concepts.md#the-data-directory), +thus disabling all 3rd-party Packages and local customizations, as well as +internally not loading any previous sessions (i.e. from any `.sublime-workspace` +files). This will help you to verify whether the behavior is, or is not, +coming from Sublime Text itself, or one of its shipped Packages. + +If the behavior is still being exhibited, it is most likely from a corrupted +shipped Package file and can be remedied by re-installing Sublime Text. + +If the behavior disappears, then you know it was coming from somewhere in +the Data Directory. + +Caution: each time Sublime Text is started this way, it wipes out any contents +of that directory if it already exists, so don't store anything important there. + +See https://www.sublimetext.com/docs/safe_mode.html for more details. + +### Diagnosing Trouble from the Data Directory + +If you have reached the conclusion that the trouble you are experiencing has +come from the Data Directory (3rd-Party Packages and/or local customization), +you can discover the source of the problem by following these steps. Note +that knowing *when* the problem started is also an asset, because the cause +will most likely have occurred just before the problem started. - Close Sublime Text if it is running. - Rename the [Data directory](../getting-started/basic-concepts.md#the-data-directory) @@ -319,17 +346,34 @@ and remove all your settings and configurations: Packages you installed and what customizations you made. - Re-start Sublime Text. -When Sublime Text starts, it will create a fresh new Data directory and -you will find that the "apparent bug" disappears. +When Sublime Text starts, it will create a fresh new Data Directory. + +#### Diagnosis by Isolating Packages + + Note: In subsequent steps, it is recommended to keep the contents of the + renamed (backup) of the problematic Data Directory unaltered for sake of + preserving the evidence. This is so that if your first attempt at isolating + the problem isn't successful, you can repeat it (using smaller or different + steps) as many times as needed until you have isolated the problem. + +Now you can re-install 3rd-Party Packages you had in place (and were working +correctly) well before the problem started. Test to verify whether the +problem is occurring after this step. + +- If the problem is *not occurring* at this point, you can continue to + diagnose by re-adding each subsequent Package one by one, until the + behavior returns, at which point you will know what to exclude. + +- On the other hand, if the problem ***is occurring***, you know the problem + is somewhere in that group of Packages, and you can take steps to further + isolate the source by reverting and repeating this step with only half of + the Packages, and keep dividing the group until you have isolated the + source. + +#### Diagnosis by Isolating Customizations -Keep in mind this also effectively de-installs every Package in -your `Installed Packages` folder, so you will probably want to -re-install the ones that are well-behaved. This sequence can also -allow you to detect which Package was misbehaving. +If you have reached this point and the problem has not returned, now you +can add your own customizations in, one at a time, until the problem +resurfaces. If/when you encounter the problem again, you will know where +to investigate further to remedy. -If it was not a misbehaving Installed Package that -was causing the problem, then adding your own -customizations back in, one at a time can also help -isolate what was causing it. Use the renamed (now-backup-copy) -[Data directory](../getting-started/basic-concepts.md#the-data-directory) -as a reference. From cf35af73b027b1c61bac9a53ef6d8885a4957b8c Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 25 May 2025 09:35:36 -0600 Subject: [PATCH 6/8] feat: add clarifications on override-file behavior --- docs/guide/extensibility/packages.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/guide/extensibility/packages.md b/docs/guide/extensibility/packages.md index 2f8dcf44..6f86527f 100644 --- a/docs/guide/extensibility/packages.md +++ b/docs/guide/extensibility/packages.md @@ -257,9 +257,16 @@ To create an override package, create a new folder under `Packages` and name it after the `.sublime-package` file you want to override, excluding the extension. -Any file you create in this package -will take precedence over any identically named file -in the original package. + +Any file you create in this package directory +will literally replace any identically named +(and identically path-ed) file +in the original package. Sublime Text literally +ignores the same-named file in the original +Package file. (This is unlike the effect of placing +files in the `User` Package where Sublime Text tries +to "merge" them into existing data when they contain +JSON data structures.) Python plugins in override packages are able to use relative imports From 8d59e1a607f7a4f12b3f389caef485dd613092f4 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 25 May 2025 13:26:18 -0600 Subject: [PATCH 7/8] feat: several enhancements... - additional clarifications added; - image added showing the "Safe Mode" announcement dialog box, which as important official information in it; - added additional information about using Safe Mode; and - refined troubleshooting information. --- .../images/safe_mode_announcement.png | Bin 0 -> 6367 bytes docs/guide/extensibility/packages.md | 52 ++++++++++++------ 2 files changed, 35 insertions(+), 17 deletions(-) create mode 100644 docs/guide/extensibility/images/safe_mode_announcement.png diff --git a/docs/guide/extensibility/images/safe_mode_announcement.png b/docs/guide/extensibility/images/safe_mode_announcement.png new file mode 100644 index 0000000000000000000000000000000000000000..2108b4a49139df82f95e3edc8261d84806256a3c GIT binary patch literal 6367 zcmc&(cQjmWw;vJYjUW;vjP|AwLG;my#1Nh6L=Q$8qK!@@uVA!9jnQH-qm4Q`A)v(0d)K{d-9Mgn&iS3^?7hz3&)(`Z5 zfI;Jl>QexKD)W5MT)J?MG^NdCogajJ!DhaXy&dg*T|7N_ja;CP07E|yUU4a29lJnY zanbV=Q5iXLkerw(udt}JsOV?_Cg=P)I$sSPFx@H*`!(4IV>vGu&!InFJTdnH0O+s% zJ*Y-z!YJq9MQ0Tq6#$?rk)C2l0|49vX{f3g1x%5$wUQQ|c)#h5EWjB&=aUe2>XOqO z&IzO;{i4nG`>RRS4rA`Wt zM~P>Y3O&HftM2-efJ@YHT7cI>9DtYc9tWV43QYY{<^u$9m5zl0F#i%s^^o&?Qh-n$ zfy5I|G2l_=oOTBtGzx>)4>EH?o$vnI-A8+GuZ)X)t{=ULX?Oum0Bjd=rmWkXl0+hl zxK1hKZItFBUjY=7tLw+D=gMti#&-veuy-?3Ryb$@?ZWp|NtBhXwzF9UoRMS&-?`^X z(bw=8Ll8soSl~0#QpwxC&h4YUJbCROBm1_e(9{jl!{fHYEtr@ zbt8wyD*&c}z{1t^8oi$62y58~)gJ_=z-ekwW>%>pt20DHWdU&1r) zYm%(c0EDO>ZsRU8;~JPc`m?4U?MIZHv1@NYvT)-JC`{Q3_ZIt~HNKfXc+^*Y2@qh=QaV)g zQe(vHZ7O-r{lHf?NT%Zb)9hp}#|`JR!`0#b#t}5dcGp1Q0>C;&LyuP12O0EWjAyMN z&_pqEEqOo4_ig@yaz`VW??46fw>^~7dP|vdWN}K7yi|IHt_7ZcN*nCpN(*2&y*E{f zXSvfIkRp0VzMRcJI20orrs)lg^-;tCUZ#IOd;Y=f`&j)NSz|Onv+CA>N8*@t-y%Qt zV~^Ejs@lJ8PuS7_%L@9RCQPf_$P}4TP^IhCrX(LrS)@002TBm)fSsW2bZ?zLx2F7o zDIS%eCE5s6=TGm~a@V83Y?SF^31(rhK`OZR{*Cu*L7k0<^FRtTu_QSIwdzvb@y-6rXAng+Ip*gdMoRV+o+BYtB3f@PMdtaxBXF#>}CB5G8mLepYnnP8~ z9iC=^3|#I{6+Fs@rx8G(xG_r=Mv^EeTQN)AuGHhIETN7M$B_eJw02QY|8lvz;L>rQ zQ0Bf70l|-Ts#r|mBwFj6Dz0o|AND%B>W5o0Y64%`^FvANOMxD8#{x~gH;_=AQwG?r zTw7^w1FqBIDXDe03N7sjWPa*}so^{!`;edABvQObjBkOg)wRuX=la>yiG6b}1_^{7 zZA+ch2Clh6R*F!BL2!sj3c+b_Z&cF!Cr$Z(x}<(_6KHNdn2Ef=+7wq!la;r=-DE2?NSC7WF=yPezQq zzSzW8Th|Z71vCvYS)>x;m6fMjq$|B@sN%WVAx_AfPJTQ4)MFAR4DyQ5Om+W_@X@TD zf^|kYZCo8Zr?0Th@l_qy`mSOFGBiQ?&(BQp{BKDs-f;Xt+s{%cnscnBsHMb}Ie)M} zW<~nL$Zd<;$MCx5fQX2x4Mu{l9sxzCXMs02RMTTkaoW2#HBX7S�jD8mGDvqnmKjT2ld)_tP~X9= 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 Date: Sun, 25 May 2025 13:33:49 -0600 Subject: [PATCH 8/8] feat: improve wording --- docs/guide/extensibility/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/extensibility/packages.md b/docs/guide/extensibility/packages.md index dd53c72a..d9c1a95f 100644 --- a/docs/guide/extensibility/packages.md +++ b/docs/guide/extensibility/packages.md @@ -313,7 +313,7 @@ Sublime Text loads packages in this order: Because Sublime Text is so customizable, it is possible for 3rd-party Packages and/or local customization to interfere with one another, or cause other problems. -You might see this, for example, seeing Python exceptions that don't make sense +You might see this, for example, as Python exceptions that don't make sense in the Console Panel, or certain functionality isn't behaving as you expect. ### Safe Mode