Merge pull request #228 from MicrosoftDocs/master

.openpublishing.redirection.json

@@ -4,6 +4,16 @@
             "source_path": "TerminalDocs/customize-settings/key-bindings.md",
             "redirect_url": "https://docs.microsoft.com/windows/terminal/customize-settings/actions",
             "redirect_document_id": true
+        },
+        {
+            "source_path": "TerminalDocs/customize-settings/global-settings.md",
+            "redirect_url": "https://docs.microsoft.com/windows/terminal/customize-settings/startup",
+            "redirect_document_id": true
+        },
+        {
+            "source_path": "TerminalDocs/customize-settings/profile-settings.md",
+            "redirect_url": "https://docs.microsoft.com/windows/terminal/customize-settings/profile-general",
+            "redirect_document_id": true
         }
     ]
 }

TerminalDocs/TOC.yml

@@ -6,12 +6,22 @@
       href: get-started.md
     - name: Customize settings
       items:
-        - name: Global settings
-          href: customize-settings/global-settings.md
-        - name: Profile settings
-          href: customize-settings/profile-settings.md
+        - name: Startup
+          href: customize-settings/startup.md
+        - name: Interaction
+          href: customize-settings/interaction.md
+        - name: Appearance
+          href: customize-settings/appearance.md
         - name: Color schemes
           href: customize-settings/color-schemes.md
+        - name: Rendering
+          href: customize-settings/rendering.md
+        - name: Profile - General
+          href: customize-settings/profile-general.md
+        - name: Profile - Appearance
+          href: customize-settings/profile-appearance.md
+        - name: Profile - Advanced
+          href: customize-settings/profile-advanced.md
         - name: Actions
           href: customize-settings/actions.md
     - name: Command line arguments

TerminalDocs/command-line-arguments.md

@@ -3,7 +3,7 @@ title: Windows Terminal command-line arguments
 description: Learn how to create command-line arguments for Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 11/11/2020
+ms.date: 1/28/2021
 ms.topic: how-to
 ---
 
@@ -37,14 +37,15 @@ Below is the full list of supported commands and options for the `wt` command li
 | `--fullscreen`, `-F` | Launches the terminal as full screen. |
 | `--focus`, `-f` | Launches the terminal in the focus mode. Can be combined with `maximized`. |
 
-> [!IMPORTANT]
-> The `--focus` and `-f` flags are only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).
-
 | Command | Parameters | Description |
 | ------- | ---------- | ----------- |
-| `new-tab`, `nt` | `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline`, `--title` | Creates a new tab. |
-| `split-pane`, `sp` | `-H, --horizontal`, `-V, --vertical`, `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline`, `--title` | Splits a new pane. |
+| `new-tab`, `nt` | `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline`, `--title`, `--tabColor` | Creates a new tab. |
+| `split-pane`, `sp` | `-H, --horizontal`, `-V, --vertical`, `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `--title`, `--tabColor`, `--size, -s size`, `commandline` | Splits a new pane. |
 | `focus-tab`, `ft` | `--target, -t tab-index` | Focuses on a specific tab. |
+| `move-focus`, `mf` | `direction` | Move focus between panes in the given direction. Accepts one of `up`, `down`, `left`, `right`. |
+
+> [!IMPORTANT]
+> The `--tabColor` parameter of the `new-tab` subcommand, `--tabColor` and `--size,-s size` parameters of the `split-pane` subcommand, and the `move-focus` subcommand are only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).
 
 > [!NOTE]
 > When opening Windows Terminal from cmd (Command Prompt), if you want to use your custom "cmd" profile settings, you will need to use the command `wt -p cmd`. Otherwise, to run your *default* profile settings, just use `wt cmd`.
@@ -259,6 +260,43 @@ Execution aliases do not work in WSL distributions. If you want to use wt.exe fr
 ---
 <!-- End tab selectors.  -->
 
+### Tab color ([Preview](https://aka.ms/terminal-preview))
+
+To open a new terminal instance with custom tab colors, use the `--tabColor` argument. This argument overrides the value defined in the profile, but can be overridden as well using the tab color picker. In the following example, a new terminal is created with two tabs of different colors:
+
+<!-- Start tab selectors. -->
+#### [Command Prompt](#tab/windows)
+
+```bash
+wt --tabColor #009999 ; new-tab --tabColor #f59218
+```
+
+#### [PowerShell](#tab/powershell)
+
+```powershell
+wt --tabColor #009999 ; new-tab --tabColor #f59218
+```
+
+#### [Linux](#tab/linux)
+
+```bash
+cmd.exe /c "wt.exe" --tabColor #009999 \; new-tab --tabColor #f59218
+```
+
+Execution aliases do not work in WSL distributions. If you want to use wt.exe from a WSL command line, you can spawn it from CMD directly by running `cmd.exe`. The `/c` option tells CMD to terminate after running and `\;` separates commands.
+
+---
+<!-- End tab selectors.  -->
+
+When `--tabColor` is set for a tab, it is associated with the first pane of this tab. Hence in a tab with multiple panes, the color will be applied only if the first pane is in focus. To set the tab color for additional panes, you will need to add the `--tabColor` parameter to the `split-pane` subcommand as well. In the example below, a tab with two panes is created with tab colors specified for each pane:
+
+```powershell
+wt new-tab --tabColor #009999 ; split-pane --tabColor #f59218
+```
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ### Tab focus
 
 To open a new terminal instance with a specific tab in focus, use the `-t` flag (or `--target`), along with the tab-index number. To open your default profile in the first tab and the "Ubuntu-18.04" profile focused in the second tab (`-t 1`), enter:

TerminalDocs/command-palette.md

@@ -3,7 +3,7 @@ title: Windows Terminal Command Palette
 description: Learn how to use the command palette in the Windows Terminal.
 author: cinnamon-msft
 ms.author: cinnamon
-ms.date: 11/11/2020
+ms.date: 1/28/2021
 ms.topic: how-to 
 ms.localizationpriority: high
 ---
@@ -26,6 +26,15 @@ If you'd like to enter a `wt` command into the command palette, you can do so by
 
 ![Windows Terminal command line mode](./images/command-palette-command-line-mode.gif)
 
+You can add a custom key binding for invoking the command palette in the command line mode directly.
+
+```json
+{ "command": "commandPalette", "launchMode": "commandLine", "keys": "" }
+```
+
+> [!IMPORTANT]
+> The `"launchMode"` setting is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ## Adding an icon to a command
 
 You can optionally add an icon to a command defined in your settings.json that appears in the command palette. This can be done by adding the `icon` property to the action. Icons can be a path to an image, a symbol from [Segoe MDL2 Assets](https://docs.microsoft.com/windows/uwp/design/style/segoe-ui-symbol-font), or any character, including emojis.

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: 11/11/2020
+ms.date: 1/28/2021
 ms.topic: how-to
 ms.localizationpriority: high
 ---
@@ -114,7 +114,7 @@ ___
 `ctrl+`, `shift+`, `alt+`
 
 > [!NOTE]
-> The `Windows` key is not supported as a modifier. 
+> The `Windows` key is not supported as a modifier.
 
 ### Modifier keys
 
@@ -136,7 +136,7 @@ ___
 
 :::row:::
 :::column span="":::
-This closes the current window and all tabs within it. If `confirmCloseAllTabs` is set to `true`, a confirmation dialog will appear to ensure you'd like to close all your tabs. More information on this setting can be found on the [Global settings page](./global-settings.md#hide-close-all-tabs-popup).
+This closes the current window and all tabs within it. If `confirmCloseAllTabs` is set to `true`, a confirmation dialog will appear to ensure you'd like to close all your tabs. More information on this setting can be found on the [Appearance page](./appearance.md#show-close-all-tabs-popup).
 
 **Command name:** `closeWindow`
 
@@ -194,7 +194,10 @@ This opens either the default or custom settings files. Without the `target` fie
 
 | Name | Necessity | Accepts | Description |
 | ---- | --------- | ------- | ----------- |
-| `target` | Optional | `"settingsFile"`, `"defaultsFile"`, `"allFiles"` | The settings file to open. |
+| `target` | Optional | `"settingsFile"`, `"defaultsFile"`, `"settingsUI"`, `"allFiles"` | The settings file to open. |
+
+> [!IMPORTANT]
+> The `"settingsUI"` value for `target` is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
 ### Toggle full screen
 
@@ -445,7 +448,7 @@ _This command is not currently bound in the default settings_.
 | ---- | --------- | ------- | ----------- |
 | `title` | Optional | String | The new title to use for this tab. If omitted, this command will revert the tab title back to its original value. |
 
-### Open tab rename text box ([Preview](https://aka.ms/terminal-preview))
+### Open tab rename text box
 
 This command changes the tab title into a text field that lets you edit the title for the current tab. Clearing the text field will reset the tab title back to the default for the current shell instance.
 
@@ -459,9 +462,6 @@ _This command is not currently bound in the default settings_.
 { "command": "openTabRenamer", "keys": "ctrl+alt+a" }
 ```
 
-> [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 ### Change tab color
 
 This command can be used to change the color of a tab to a specific value.
@@ -498,6 +498,33 @@ This command can be used to open the color picker for the active tab. The color
 { "command": "openTabColorPicker" }
 ```
 
+### Move tab ([Preview](https://aka.ms/terminal-preview))
+
+This command moves the tab "backward" and "forward", which is equivalent to "left" and "right" in left-to-right UI.
+
+**Command name:** `moveTab`
+
+**Default binding:**
+
+_This command is not currently bound in the default settings_.
+
+```json
+// Move tab backward (left in LTR)
+{ "command": { "action": "moveTab", "direction": "backward" }, "keys": "" }
+
+// Move tab forward (right in LTR)
+{ "command": { "action": "moveTab", "direction": "forward" }, "keys": "" }
+```
+
+#### Actions
+
+| Name | Necessity | Accepts | Description |
+| ---- | --------- | ------- | ----------- |
+| `direction` | Required | `"backward"`, `"forward"` | Direction in which the tab will move. |
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 <br />
 
 ___
@@ -518,7 +545,7 @@ This closes the active pane. If there aren't any split panes, this will close th
 
 ### Move pane focus
 
-This changes focus to a different pane depending on the direction.
+This changes focus to a different pane depending on the direction. Setting the `direction` to `"previous"` will move focus to the most recently used pane.
 
 **Command name:** `moveFocus`
 
@@ -528,16 +555,20 @@ This changes focus to a different pane depending on the direction.
 { "command": { "action": "moveFocus", "direction": "down" }, "keys": "alt+down" },
 { "command": { "action": "moveFocus", "direction": "left" }, "keys": "alt+left" },
 { "command": { "action": "moveFocus", "direction": "right" }, "keys": "alt+right" },
-{ "command": { "action": "moveFocus", "direction": "up" }, "keys": "alt+up" }
+{ "command": { "action": "moveFocus", "direction": "up" }, "keys": "alt+up" },
+{ "command": { "action": "moveFocus", "direction": "previous" }, "keys": "ctrl+alt+left" }
 ```
 
 #### Actions
 
 | Name | Necessity | Accepts | Description |
 | ---- | --------- | ------- | ----------- |
-| `direction` | Required | `"left"`, `"right"`, `"up"`, `"down"` | Direction in which the focus will move. |
+| `direction` | Required | `"left"`, `"right"`, `"up"`, `"down"`, `"previous"` | Direction in which the focus will move. |
+
+> [!IMPORTANT]
+> The `"previous"` direction is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
-### Zoom a pane ([Preview](https://aka.ms/terminal-preview))
+### Zoom a pane
 
 :::row:::
 :::column span="":::
@@ -558,9 +589,6 @@ This expands the focused pane to fill the entire contents of the window.
 :::column-end:::
 :::row-end:::
 
-> [!IMPORTANT]
-> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 ### Resize a pane
 
 This changes the size of the active pane.
@@ -595,8 +623,8 @@ This halves the size of the active pane and opens another. Without any arguments
 { "command": { "action": "splitPane", "split": "auto", "splitMode": "duplicate" }, "keys": "alt+shift+d" },
 
 // In defaults.json
-{ "command": { "action": "splitPane", "split": "horizontal"}, "keys": "alt+shift+-" },
-{ "command": { "action": "splitPane", "split": "vertical"}, "keys": "alt+shift+plus" }
+{ "command": { "action": "splitPane", "split": "horizontal" }, "keys": "alt+shift+-" },
+{ "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+shift+plus" }
 ```
 
 #### Actions
@@ -610,6 +638,10 @@ This halves the size of the active pane and opens another. Without any arguments
 | `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. |
 | `splitMode` | Optional | `"duplicate"` | Controls how the pane splits. Only accepts `"duplicate"`, which will duplicate the focused pane's profile into a new pane. |
+| `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 `size` parameter is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
 <br />
 
@@ -682,9 +714,6 @@ This scrolls the screen up by the number of rows defined by `"rowsToScroll"`. If
 | ---- | --------- | ------- | ----------- |
 | `rowsToScroll` | Optional | Integer | The number of rows to scroll. |
 
-> [!IMPORTANT]
-> The `"rowsToScroll"` action is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 ### Scroll down
 
 This scrolls the screen down by the number of rows defined by `"rowsToScroll"`. If `"rowsToScroll"` is not provided, it will scroll down the amount defined by the system default, which is the same amount as mouse scrolling.
@@ -703,9 +732,6 @@ This scrolls the screen down by the number of rows defined by `"rowsToScroll"`.
 | ---- | --------- | ------- | ----------- |
 | `rowsToScroll` | Optional | Integer | The number of rows to scroll. |
 
-> [!IMPORTANT]
-> The `"rowsToScroll"` action is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
-
 ### Scroll up a whole page
 
 This scrolls the screen up by a whole page, which is the height of the window.
@@ -730,6 +756,36 @@ This scrolls the screen down by a whole page, which is the height of the window.
 { "command": "scrollDownPage", "keys": "ctrl+shift+pgdn" }
 ```
 
+### Scroll to the earliest history
+
+This scrolls the screen up to the top of the input buffer.
+
+**Command name:** `scrollToTop`
+
+**Default binding:**
+
+```json
+{ "command": "scrollToTop", "keys": "ctrl+shift+home" }
+```
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+### Scroll to the latest history
+
+This scrolls the screen down to the bottom of the input buffer.
+
+**Command name:** `scrollToBottom`
+
+**Default binding:**
+
+```json
+{ "command": "scrollToBottom", "keys": "ctrl+shift+end" }
+```
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 <br />
 
 ___
@@ -767,18 +823,21 @@ This resets the text size to the default value.
 { "command": "resetFontSize", "keys": "ctrl+0" }
 ```
 
-### Toggle retro terminal effects
+### Toggle pixel shader effects
 
-This toggles the "retro terminal effect", which is enabled with the profile setting `experimental.retroTerminalEffect`.
+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`.
 
-**Command name:** `toggleRetroEffect`
+**Command name:** `toggleShaderEffects`
 
 **Default binding:**
 
 ```json
-{ "command": "toggleRetroEffect" }
+{ "command": "toggleShaderEffects" }
 ```
 
+> [!CAUTION]
+> The `toggleRetroEffect` action is no longer available in versions 1.6 and later. It is recommended that you use `toggleShaderEffects` instead.
+
 ### Set the color scheme
 
 Changes the active color scheme.