Add Dynamic Profile Generators

doc/user-docs/UsingJsonSettings.md

@@ -1,12 +1,22 @@
 # Editing Windows Terminal JSON Settings
 
-One way (currently the only way) to configure Windows Terminal is by editing the profiles.json settings file. At
-the time of writing you can open the settings file in your default editor by selecting
-`Settings` from the WT pull down menu.
+One way (currently the only way) to configure Windows Terminal is by editing the
+`profiles.json` settings file. At the time of writing you can open the settings
+file in your default editor by selecting `Settings` from the WT pull down menu.
 
-The settings are stored in the file `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_<randomString>\RoamingState\profiles.json` 
+The settings are stored in the file `$env:LocalAppData\Packages\Microsoft.WindowsTerminal_<randomString>\RoamingState\profiles.json`.
 
-Details of specific settings can be found [here](../cascadia/SettingsSchema.md). A general introduction is provided below.
+As of [#2515](https://github.com/microsoft/terminal/pull/2515), the settings are
+split into _two_ files: a hardcoded `defaults.json`, and `profiles.json`, which
+contains the user settings. Users should only be concerned with the contents of
+the `profiles.json`, which contains their customizations. The `defaults.json`
+file is only provided as a reference of what the default settings are. For more
+details on how these two files work, see [Settings
+Layering](#settings-layering). To view the default settings file, click on the
+"Settings" button while holding the <kbd>Alt</kbd> key.
+
+Details of specific settings can be found [here](../cascadia/SettingsSchema.md).
+A general introduction is provided below.
 
 The settings are grouped under four headings:
 
@@ -17,12 +27,13 @@ The settings are grouped under four headings:
 
 ## Global Settings
 
-These settings define startup defaults.
+These settings define startup defaults, and application-wide settings that might
+not affect a particular terminal instance.
 
 * Theme
 * Title Bar options
 * Initial size
-* Default profile used when WT is started
+* Default profile used when the Windows Terminal is started
 
 Example settings include
 
@@ -31,10 +42,13 @@ Example settings include
     "initialCols" : 120,
     "initialRows" : 50,
     "requestedTheme" : "system",
-    "keybinding" : []
+    "keybindings" : []
     ...
 ```
 
+These global properties can exist either in the root json object, or in and
+object under a root property `"globals"`.
+
 ## Key Bindings
 
 This is an array of key chords and shortcuts to invoke various commands.
@@ -43,10 +57,29 @@ Each command can have more than one key binding.
 NOTE: Key bindings is a subfield of the global settings and
 key bindings apply to all profiles in the same manner.
 
+For example, here's a sample of the default keybindings:
+
+```json
+{
+    "keybindings":
+    [
+        { "command": "closePane", "keys": ["ctrl+shift+w"] },
+        { "command": "copy", "keys": ["ctrl+shift+c"] },
+        { "command": "newTab", "keys": ["ctrl+shift+t"] },
+        // etc.
+    ]
+}
+
+```
+
 ## Profiles
 
-A profile contains the settings applied when a new WT tab is opened. Each profile is identified by a GUID and contains
-a number of other fields.
+A profile contains the settings applied when a new WT tab is opened. Each
+profile is identified by a GUID and contains a number of other fields.
+
+> 👉 **Note**: The `guid` property is the unique identifier for a profile. If
+> multiple profiles all have the same `guid` value, you may see unexpected
+> behavior.
 
 * Which command to execute on startup - this can include arguments.
 * Starting directory
@@ -77,6 +110,14 @@ The profile GUID is used to reference the default profile in the global settings
 
 The values for background image stretch mode are documented [here](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.media.stretch)
 
+### Hiding a profile
+
+If you want to remove a profile from the list of profiles in the new tab
+dropdown, but keep the profile around in your `profiles.json` file, you can add
+the property `"hidden": true` to the profile's json. This can also be used to
+remove the default `cmd` and PowerShell profiles, if the user does not wish to
+see them.
+
 ##  Color Schemes
 
 Each scheme defines the color values to be used for various terminal escape sequences.
@@ -97,6 +138,62 @@ Each schema is identified by the name field. Examples include
 
 The schema name can then be referenced in one or more profiles.
 
+## Settings layering
+
+The runtime settings are actually constructed from _three_ sources:
+* The default settings, which are hardcoded into the application, and available
+  in `defaults.json`. This includes the default keybindings, color schemes, and
+  profiles for both Windows PowerShell and Command Prompt (`cmd.exe`).
+* Dynamic Profiles, which are generated at runtime. These include Powershell
+  Core, the Azure Cloud Shell connector, and profiles for and WSL distros.
+* The user settings from `profiles.json`.
+
+Settings from each of these sources are "layered" upon the settings from
+previous sources. In this manner, the user settings in `profiles.json` can
+contain _only the changes from the default settings_. For example, if a user
+would like to only change the color scheme of the default `cmd` profile to
+"Solarized Dark", you could change your cmd profile to the following:
+
+```js
+        {
+            // Make changes here to the cmd.exe profile
+            "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
+            "colorScheme": "Solarized Dark"
+        }
+```
+
+Here, we're know we're changing the `cmd` profile, because the `guid`
+`"{0caa0dad-35be-5f56-a8ff-afceeeaa6101}"` is `cmd`'s unique GUID. Any profiles
+with that GUID will all be treated as the same object. Any changes in that
+profile will overwrite those from the defaults.
+
+Similarly, you can overwrite settings from a color scheme by defining a color
+scheme in `profiles.json` with the same name as a default color scheme.
+
+If you'd like to unbind a keystroke that's bound to an action in the default
+keybindings, you can set the `"command"` to `"unbound"` or `null`. This will
+allow the keystroke to fallthough to the commandline application instead of
+performing the default action.
+
+### Dynamic Profiles
+
+When dynamic profiles are created at runtime, they'll be added to the
+`profiles.json` file. You can identify these profiles by the presence of a
+`"source"` property. These profiles are tied to their source - if you uninstall
+a linux distro, then the profile will remain in your `profiles.json` file, but
+the profile will be hidden.
+
+If you'd like to disable a particular dynamic profile source, you can add that
+`source` to the global `"disabledProfileSources"` array. For example, if you'd
+like to hide all the WSL profiles, you could add the following setting:
+
+```json
+
+    "disabledProfileSources": ["Microsoft.Terminal.WSL"],
+    ...
+
+```
+
 ## Configuration Examples:
 
 ### Add a custom background to the WSL Debian terminal profile
@@ -127,15 +224,17 @@ then you should use the URI style path name given in the above example.
 More information about UWP URI schemes [here](https://docs.microsoft.com/en-us/windows/uwp/app-resources/uri-schemes).
 3. Instead of using a UWP URI you can use a:
     1. URL such as
-`http://open.esa.int/files/2017/03/Mayer_and_Bond_craters_seen_by_SMART-1-350x346.jpg` 
+`http://open.esa.int/files/2017/03/Mayer_and_Bond_craters_seen_by_SMART-1-350x346.jpg`
     2. Local file location such as `C:\Users\Public\Pictures\openlogo.jpg`
 
-### Adding Copy and Paste Keybindings 
+### Adding Copy and Paste Keybindings
 
-As of [#1093](https://github.com/microsoft/terminal/pull/1093) (first available in Windows Terminal v0.3), the Windows Terminal now
-supports copy and paste keyboard shortcuts. However, if you installed and ran
-the terminal before that, you won't automatically get the new keybindings added
-to your settings. If you'd like to add shortcuts for copy and paste, you can do so by inserting the following objects into your `globals.keybindings` array:
+As of [#1093](https://github.com/microsoft/terminal/pull/1093) (first available
+in Windows Terminal v0.3), the Windows Terminal now supports copy and paste
+keyboard shortcuts. However, if you installed and ran the terminal before that,
+you won't automatically get the new keybindings added to your settings. If you'd
+like to add shortcuts for copy and paste, you can do so by inserting the
+following objects into your `globals.keybindings` array:
 
 ```json
 { "command": "copy", "keys": ["ctrl+shift+c"] },
@@ -171,5 +270,10 @@ You can even set multiple keybindings for a single action if you'd like. For exa
 will bind both <kbd>ctrl+shift+v</kbd> and
 <kbd>shift+Insert</kbd> to `paste`.
 
-Note: If you set your copy keybinding to `"ctrl+c"`, you won't be able to send an interrupt to the commandline application using <kbd>Ctrl+C</kbd>. This is a bug, and being tracked by [#2258](https://github.com/microsoft/terminal/issues/2285). 
-Additionally, if you set `paste` to `"ctrl+v"`, commandline applications won't be able to read a ctrl+v from the input. For these reasons, we suggest `"ctrl+shift+c"` and `"ctrl+shift+v"`
+Note: If you set your copy keybinding to `"ctrl+c"`, you won't be able to send
+an interrupt to the commandline application using <kbd>Ctrl+C</kbd>. This is a
+bug, and being tracked by
+[#2258](https://github.com/microsoft/terminal/issues/2285). Additionally, if you
+set `paste` to `"ctrl+v"`, commandline applications won't be able to read a
+ctrl+v from the input. For these reasons, we suggest `"ctrl+shift+c"` and
+`"ctrl+shift+v"`

src/cascadia/CascadiaPackage/CascadiaPackage.wapproj

@@ -249,6 +249,7 @@
     <Content Include="$(OpenConsoleDir)res\terminal\Wide310x150Logo.scale-400.png">
       <Link>Images\Wide310x150Logo.scale-400.png</Link>
     </Content>
+    <!-- Profile Icons -->
     <Content Include="ProfileIcons\{0caa0dad-35be-5f56-a8ff-afceeeaa6101}.scale-100.png" />
     <Content Include="ProfileIcons\{0caa0dad-35be-5f56-a8ff-afceeeaa6101}.scale-200.png" />
     <Content Include="ProfileIcons\{574e775e-4f2a-5b96-ac1e-a2962a402336}.scale-100.png" />
@@ -259,9 +260,16 @@
     <Content Include="ProfileIcons\{9acb9455-ca41-5af7-950f-6bca1bc9722f}.scale-200.png" />
     <Content Include="ProfileIcons\{b453ae62-4e3d-5e58-b989-0a998ec441b8}.scale-100.png" />
     <Content Include="ProfileIcons\{b453ae62-4e3d-5e58-b989-0a998ec441b8}.scale-200.png" />
+    <!-- Default Settings -->
+    <Content Include="$(OpenConsoleDir)src\cascadia\TerminalApp\defaults.json">
+      <Link>defaults.json</Link>
+    </Content>
+    <!-- Resources -->
     <PRIResource Include="Resources\en-US\Resources.resw" />
   </ItemGroup>
+
   <Import Project="$(OpenConsoleDir)src\wap-common.build.post.props" />
+
   <ItemGroup>
     <ProjectReference Include="..\WindowsTerminal\WindowsTerminal.vcxproj" />
     <ProjectReference Include="..\..\host\exe\Host.EXE.vcxproj" />