Merge release-1.13 into main

TerminalDocs/customize-settings/actions.md

@@ -3,7 +3,7 @@ title: Windows Terminal Actions
 description: Learn how to create custom actions for Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 10/15/2021
+ms.date: 02/03/2022
 ms.topic: how-to
 ---
 
@@ -132,7 +132,7 @@ ___
 
 ## Application-level commands
 
-### Quit ([Preview](https://aka.ms/terminal-preview))
+### Quit
 
 This closes all open terminal windows. A confirmation dialog will appear in the current window to ensure you'd like to close all windows.
 
@@ -144,9 +144,6 @@ This closes all open terminal windows. A confirmation dialog will appear in the
 { "command": "quit" }
 ```
 
-> [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 ### Close window
 
 :::row:::
@@ -398,12 +395,16 @@ This creates a new tab. Without any arguments, this will open the default profil
 | ---- | --------- | ------- | ----------- |
 | `commandline` | Optional | Executable file name as a string | Executable run within the tab. |
 | `startingDirectory` | Optional | Folder location as a string | Directory in which the tab will open. |
+| `elevate` | Optional | `true`, `false`, `null` | Overrides the [`elevate`](./profile-general.md#automatically-run-as-administrator-preview) property of the profile. When omitted, this action will behave according to the profile's `elevate` setting. When set to `true` or `false`, this action will behave as though the profile was set with `"elevate": true` or `"elevate": false` (respectively). |
 | `tabTitle` | Optional | String | Title of the new tab. |
 | `index` | Optional | Integer | Profile that will open based on its position in the dropdown (starting at 0). |
 | `profile` | Optional | Profile's name or GUID as a string | Profile that will open based on its GUID or name. |
 | `colorScheme` | Optional | The name of a color scheme as a string | The scheme to use instead of the profile's set `colorScheme` |
 | `suppressApplicationTitle` | Optional | `true`, `false` | When set to `false`, applications can change the tab title by sending title change messages. When set to `true`, these messages are suppressed. If not provided, the behavior is inherited from the profile's settings. In order to enter a new tab title and have that title persist, this must be set to true. |
 
+> [!IMPORTANT]
+> The `elevate` property is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ### Open next tab
 
 This opens the tab to the right of the current one.
@@ -796,6 +797,7 @@ This halves the size of the active pane and opens another. Without any arguments
 | `split` | Required | `"vertical"`, `"horizontal"`, `"auto"`, `"up"`, `"right"`, `"down"`, `"left"` | How the pane will split. `"auto"` will split in the direction that provides the most surface area. |
 | `commandline` | Optional | Executable file name as a string | Executable run within the pane. |
 | `startingDirectory` | Optional | Folder location as a string | Directory in which the pane will open. |
+| `elevate` | Optional | `true`, `false`, `null` | Overrides the [`elevate`](./profile-general.md#automatically-run-as-administrator-preview) property of the profile. When omitted, this action will behave according to the profile's `elevate` setting. When set to `true` or `false`, this action will behave as though the profile was set with `"elevate": true` or `"elevate": false` (respectively). |
 | `tabTitle` | Optional | String | Title of the tab when the new pane is focused. |
 | `index` | Optional | Integer | Profile that will open based on its position in the dropdown (starting at 0). |
 | `profile` | Optional | Profile's name or GUID as a string | Profile that will open based on its GUID or name. |
@@ -805,7 +807,7 @@ This halves the size of the active pane and opens another. Without any arguments
 | `size` | Optional | Float | Specify how large the new pane should be, as a fraction of the current pane's size. `1.0` would be "all of the current pane", and `0.0` is "None of the parent". Defaults to `0.5`. |
 
 > [!IMPORTANT]
-> The `"up"`, `"right"`, `"down"`, and `"left"` options for `split` are only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+> The `elevate` property is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
 <br />
 
@@ -837,7 +839,7 @@ This copies the selected terminal content to your clipboard. If no selection exi
  | `singleLine` | Optional | `true`, `false` | When `true`, the copied content will be copied as a single line. When `false`, newlines persist from the selected text. |
  | `copyFormatting` | Optional | `true`, `false`, `"all"`, `"none"`, `"html"`, `"rtf"` | When `true`, the color and font formatting of the selected text is also copied to your clipboard. When `false`, only plain text is copied to your clipboard. You can also specify which formats you would like to copy. When `null`, the global `"copyFormatting"` behavior is inherited. |
 
-### Keyboard Selection ([Preview](https://aka.ms/terminal-preview))
+### Keyboard selection
 
 This modifies an existing selection. If no selection exists, the key chord is sent directly to the terminal.
 
@@ -874,9 +876,6 @@ This modifies an existing selection. If no selection exists, the key chord is se
 | `direction` | Required | `"left"`, `"right"`, `"up"`, `"down"` | Direction in which the selection endpoint will move. |
 | `mode` | Required | `"char"`, `"word"`, `"view"`, `"buffer"` | Controls how much the endpoint moves by. |
 
-> [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 ### Paste
 
 This inserts the content that was copied onto the clipboard.
@@ -986,6 +985,24 @@ This scrolls the screen down to the bottom of the input buffer.
 
 <br />
 
+### Clear buffer
+
+This action can be used to manually clear the terminal buffer. This is useful for scenarios where you're not sitting at a command-line shell prompt and can't easily run `Clear-Host`/`cls`/`clear`.
+
+**Command name:** `clearBuffer`
+
+**Default bindings:**
+
+```json
+{ "command": { "action": "clearBuffer", "clear": "all" } }
+```
+
+#### Actions
+
+| Name | Necessity | Accepts | Description |
+| ---- | --------- | ------- | ----------- |
+| `clear` | Optional | `"screen"`, `"scrollback"`, `"all"` | What part of the screen to clear. <ul><li>`"screen"`: Clear the terminal viewport content. Leaves the scrollback untouched. Moves the cursor row to the top of the viewport (unmodified).</li><li>`"scrollback"`: Clear the scrollback. Leaves the viewport untouched.</li><li>`"all"` (_default_): Clear the scrollback and the visible viewport. Moves the cursor row to the top of the viewport. </li></ul> |
+
 ___
 
 ## Visual adjustment commands
@@ -1024,6 +1041,31 @@ This resets the text size to the default value.
 { "command": "resetFontSize", "keys": "ctrl+numpad_0" }
 ```
 
+### Adjust opacity ([Preview](https://aka.ms/terminal-preview))
+
+This changes the opacity of the window. If `relative` is set to true, it will adjust the opacity relative to the current opacity. Otherwise, it will set the opacity directly to the given `opacity`
+
+**Command name:** `adjustOpacity`
+
+**Default bindings:**
+
+```json
+{ "command": { "action": "adjustOpacity", "relative": false, "opacity": 0 } },
+{ "command": { "action": "adjustOpacity", "relative": false, "opacity": 25 } },
+{ "command": { "action": "adjustOpacity", "relative": false, "opacity": 50 } },
+{ "command": { "action": "adjustOpacity", "relative": false, "opacity": 100 } }
+```
+
+#### Actions
+
+| Name | Necessity | Accepts | Description |
+| ---- | --------- | ------- | ----------- |
+| `opacity` | Optional | Integer | How opaque the terminal should become or how much the opacity should be changed by, depending on the value of `relative` |
+| `relative` | Optional | Boolean | If true, then adjust the current opacity by the given `opacity` parameter. If false, set the opacity to exactly that value. |
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ### Toggle pixel shader effects
 
 This toggles any pixel shader effects enabled in the terminal. If the user specified a valid shader with `experimental.pixelShaderPath`, this action will toggle that shader on/off. This will also toggle the "retro terminal effect", which is enabled with the profile setting `experimental.retroTerminalEffect`.
@@ -1061,6 +1103,31 @@ Changes the active color scheme.
 
 ___
 
+## Buffer exporting
+
+### Export buffer ([Preview](https://aka.ms/terminal-preview))
+
+This allows the user to export the text of the buffer to a file. If the file doesn't exist, it will be created. If the file already exists, its contents will be replaced with the Terminal buffer text.
+
+**Command name:** `exportBuffer`
+
+**Default bindings:**
+
+```json
+{ "command": { "action": "exportBuffer" } }
+```
+
+#### Actions
+
+| Name | Necessity | Accepts | Description |
+| ---- | --------- | ------- | ----------- |
+| `path` | Optional | String | If provided, then the Terminal will export the buffer contents to the given file. Otherwise, the terminal will open a file picker to choose the file to export to. |
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+___
+
 ## Global commands
 
 ### Global summon
@@ -1187,7 +1254,7 @@ If you'd like to change the behavior of the `quakeMode` action, we recommended c
 
 ___
 
-## Run multiple actions ([Preview](https://aka.ms/terminal-preview))
+## Run multiple actions
 
 This action allows the user to bind multiple sequential actions to one command. 
 
@@ -1221,9 +1288,6 @@ This action allows the user to bind multiple sequential actions to one command.
 }}
 ```
 
-> [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 <br />
 
 ___

TerminalDocs/customize-settings/interaction.md

@@ -3,7 +3,7 @@ title: Windows Terminal Interaction Settings
 description: Learn how to customize interaction settings within Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 10/05/2021
+ms.date: 02/03/2022
 ms.topic: how-to
 ---
 
@@ -59,6 +59,23 @@ When this is set to `true` and you copy text in a rectangular (block) selection
 
 ___
 
+## Trim trailing whitespace on paste ([Preview](https://aka.ms/terminal-preview))
+
+When enabled, the terminal will automatically trim trailing whitespace characters when pasting text to the terminal.
+
+**Property name:** `trimPaste`
+
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `true`
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+___
+
 ## Word delimiters
 
 This determines the word delimiters used in a double-click selection. Word delimiters are characters that specify where the boundary is between two words. The most common examples are spaces, semicolons, commas, and periods.

TerminalDocs/customize-settings/profile-advanced.md

@@ -3,7 +3,7 @@ title: Windows Terminal Advanced Profile Settings
 description: Learn how to customize the advanced profile settings within Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 10/19/2021
+ms.date: 02/03/2022
 ms.topic: how-to
 ---
 
@@ -137,6 +137,25 @@ Controls what happens when the application emits a BEL character. When set to `"
 
 ___
 
+## Experimental text rendering engine ([Preview](https://aka.ms/terminal-preview))
+
+Enables use of the experimental text rendering engine for the profile. This is an experimental feature and its continued existence is not guaranteed. A new instance of the profile needs to be opened in order for this setting to take effect.
+
+**Property name:** `experimental.useAtlasEngine`
+
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+<br />
+
+___
+
 ## Unique identifier
 
 Profiles can use a GUID as a unique identifier. To make a profile your default profile, it needs a GUID for the `defaultProfile` global setting.

TerminalDocs/customize-settings/profile-appearance.md

@@ -3,7 +3,7 @@ title: Windows Terminal Appearance Profile Settings
 description: Learn how to customize the appearance profile settings within Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 10/08/2021
+ms.date: 02/03/2022
 ms.topic: how-to
 ---
 
@@ -328,7 +328,7 @@ ___
 
 ## Transparency
 
-### Opacity ([Preview](https://aka.ms/terminal-preview))
+### Opacity
 
 :::row:::
 :::column span="":::
@@ -356,7 +356,7 @@ When `useAcrylic` is set to `true`, the window will use the acrylic material to
 > Prior to Windows Terminal version 1.12, this setting was `acrylicOpacity`, was a float that accepted 0.0-1.0 which defaulted to 0.5, and the opacity would only apply if `useAcrylic` was set to true. On 1.12+, `acrylicOpacity` will gracefully continue to work as the equivalent `opacity` value.
 
 > [!IMPORTANT]
-> Unblurred opacity (`"useAcrylic": false`) only works on Windows 11 or above with [Windows Terminal Preview](https://aka.ms/terminal-preview).
+> Unblurred opacity (`"useAcrylic": false`) only works on Windows 11.
 
 ### Enable acrylic
 
@@ -462,7 +462,7 @@ This sets the background color of a selection within the profile. This will over
 
 **Accepts:** Color as a string in hex format: `"#rgb"` or `"#rrggbb"`
 
-### Adjust indistinguishable colors ([Preview](https://aka.ms/terminal-preview))
+### Adjust indistinguishable colors
 
 When set to true, this will (when necessary) adjust the foreground color to make it more visible, based on the background color.
 
@@ -474,9 +474,6 @@ When set to true, this will (when necessary) adjust the foreground color to make
 
 **Default value:** `true`
 
-> [!IMPORTANT]
-> This feature only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 ### Cursor color
 
 This sets the cursor color of the profile. This will override the `cursorColor` set in the color scheme if `colorScheme` is set.

TerminalDocs/customize-settings/profile-general.md

@@ -3,7 +3,7 @@ title: Windows Terminal General Profile Settings
 description: Learn how to customize the general profile settings within Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 04/14/2021
+ms.date: 02/03/2022
 ms.topic: how-to
 ---
 
@@ -105,7 +105,32 @@ If set, this will replace the `name` as the title to pass to the shell on startu
 **Accepts:** String
 
 <br />
+___
+
+## Automatically run as Administrator ([Preview](https://aka.ms/terminal-preview))
+
+If set, this profile will automatically open up in an "elevated" window (running as Administrator) by default. If you run this profile from an unelevated window, then a new elevated terminal window will be created to host this profile. If you launch this profile from an already elevated window, then it will open as a new tab.
+
+When this property is set to `false`, opening this profile in an elevated window will not launch an _unelevated_ window to host this profile. The profile will simply open in the elevated window, running as Administrator.
+
+If you set this property in `profiles.defaults`, then _all_ profiles will launch as Administrator by default, unless overrided by specifically setting this to false.
+
+This property can be overridden in the [`newTab`](./actions.md#new-tab) and [`splitPane`](./actions.md#split-a-pane) actions, with the `elevate` property.
+
+Elevated and unelevated tabs cannot exist in the same terminal window. For more details, please see the [FAQ](./../faq.yml#can-you-have-have-tabs-running-as-administrator--elevated--in-unelevated-terminal-windows).
+
+**Property name:** `elevate`
 
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+<br />
 ___
 
 ## Hide profile from dropdown

TerminalDocs/customize-settings/startup.md

@@ -3,7 +3,7 @@ title: Windows Terminal Startup Settings
 description: Learn how to customize startup settings within Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 10/08/2021
+ms.date: 02/03/2022
 ms.topic: how-to
 ---
 
@@ -64,7 +64,7 @@ Note: if the Windows Terminal startup task entry is disabled either by org polic
 
 ___
 
-## Behavior when starting a new terminal session ([Preview](https://aka.ms/terminal-preview))
+## Behavior when starting a new terminal session
 
 When set to `"defaultProfile"`, Windows Terminal will start a new session by opening a single tab with your default profile.
 
@@ -86,9 +86,6 @@ Note: Currently, Windows Terminal will save the following information:
 
 **Default value:** `"defaultProfile"`
 
-> [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 <br />
 
 ___