From 6247f7d3c76e45e3116ebc92f0d50fb047baf46a Mon Sep 17 00:00:00 2001 From: Christopher Nguyen <91625426+nguyen-dows@users.noreply.github.com> Date: Fri, 19 May 2023 15:08:18 -0700 Subject: [PATCH] Merge Main to Live (#670) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(powerline): update oh-my-posh CLI (#632) * Themes updates for 1.17 (#634) Documents a whole pile of stuff from 1.17: * `useMica` https://github.com/microsoft/terminal/pull/13935 * theme pairs https://github.com/microsoft/terminal/pull/14497 * scheme pairs https://github.com/microsoft/terminal/pull/14064 * closes #626 * Default prompt icon info, resolves https://github.com/MicrosoftDocs/terminal/issues/625 (#642) * Add app execution alias section (#643) * Add autoHideWindows Resolves https://github.com/MicrosoftDocs/terminal/issues/633 * Add color theme FAQs * Remove code brackets from headers Resolves https://github.com/MicrosoftDocs/terminal/issues/637 * Fix default if no command specified Called out in https://github.com/MicrosoftDocs/terminal/issues/638 * Add note differentiating null from no setting for Starting Directory. Resolves https://github.com/MicrosoftDocs/terminal/issues/624 * add the adobe-target metadata for A/B testing (#646) could you please help to merge this metadata change (adobe-target=true) to main branch and then to live? This is to enable A/B testing ability across many url base paths so we can improve Learn user experience based on data-driven decisions. This meta (adobe-target) itself will not change how your content is displayed or modify any other UI behaviors so it is safe to merge. * Add documentation to include information about enable/disable read-only mode functionality (#645) * Update actions to include new enable and disable functionality * Update panes to include new enable and disable functionality * Many updates to commandline args docs, and some missing actions too (#649) * Many updates to commandline args docs, and some missing actions too * Fix anchor link warnings --------- Co-authored-by: Matt Wojciakowski * Remove Dynamic SSH profiles from doc since it has not been implemente… (#650) * Remove Dynamic SSH profiles from doc since it has not been implemented yet. * Updated authors and date * Shelfing read-only mode docs until it goes in a future release (#653) * Added maximum history size (#657) * added maximum history size * empty commit to poke the bot * remove instances of Preview for 1.15 features (#669) * remove enableReadOnlyMode and disableReadyOnlyMode docs in panes until it goes live in a future release (#672) --------- Co-authored-by: Jan De Dobbeleer <2492783+JanDeDobbeleer@users.noreply.github.com> Co-authored-by: Mike Griese Co-authored-by: Matt Wojciakowski Co-authored-by: juchen-ms Co-authored-by: Alex Noble <6237394+Swinkid@users.noreply.github.com> --- TerminalDocs/command-line-arguments.md | 75 ++++++++-- TerminalDocs/customize-settings/actions.md | 139 +++++++++++++----- .../customize-settings/profile-advanced.md | 8 +- TerminalDocs/tutorials/ssh.md | 9 +- 4 files changed, 175 insertions(+), 56 deletions(-) diff --git a/TerminalDocs/command-line-arguments.md b/TerminalDocs/command-line-arguments.md index c8e8521f..0f383838 100644 --- a/TerminalDocs/command-line-arguments.md +++ b/TerminalDocs/command-line-arguments.md @@ -1,9 +1,9 @@ --- 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: 03/10/2023 +author: nguyen-dows +ms.author: chrnguyen +ms.date: 05/19/2023 ms.topic: how-to --- @@ -35,14 +35,29 @@ Below is the full list of supported commands and options for the `wt` command li | Option | Description | | ------ | ----------- | -| `--help`, `-h`, `-?`, `/?` | Displays the help message. | -| `--maximized`, `-M` | Launches the terminal maximized. | -| `--fullscreen`, `-F` | Launches the terminal as full screen. | -| `--focus`, `-f` | Launches the terminal in the focus mode. Can be combined with `maximized`. | -| `--window`, `-w` `` | Launches the terminal in a specific window. | +| `--help, -h, -?, /?` | Displays the help message. | +| `--maximized, -M` | Launches the terminal maximized. | +| `--fullscreen, -F` | Launches the terminal as full screen. | +| `--focus, -f` | Launches the terminal in the focus mode. Can be combined with `maximized`. | +| `--pos x,y` | Launches the at the given position. `x` or `y` can be omitted, to use the default value from the settings. | +| `--window, -w window-id` | Runs the given command in a specific window. | + + +The `--window` parameter can be used to send commands to existing terminal windows. + +`window-id` may either be the integer ID of a window, or the name of a window. It also accepts the following reserved values: +* `new` or `-1`: Always run this command in a new window +* `last` or `0`: Always run this command in the most recently used window + +If no window exists with the given `window-id`, then a new window will be +created with that id/name. + +For example, running `wt -w _quake` will open a new ["quake window"](./tips-and-tricks.md#quake-mode). Running that command again will open a new tab in the existing quake window. ### New tab command +Used to create a new tab. See also the [`newTab` action](./customize-settings/actions.md#new-tab). + | Command | Parameter | Description | Values | | ------- | ---------- | ----------- | ------ | | `new-tab`, `nt` | `--profile, -p profile-name` | Creates a new tab based on the profile name assigned. | Profile name | @@ -50,12 +65,17 @@ Below is the full list of supported commands and options for the `wt` command li | `new-tab`, `nt` | `commandline` | Creates a new tab based on the command line assigned. | Executable with optional commands | | `new-tab`, `nt` | `--title` | Creates a new tab with the title assigned. | Text to use as the tab title | | `new-tab`, `nt` | `--tabColor` | Creates a new tab with the tab color assigned. | Hex color as #RGB or #RRGGBB | +| `new-tab`, `nt` | `--suppressApplicationTitle` | Override the profile's `suppressApplicationTilte` setting, and set it to `true` | | +| `new-tab`, `nt` | `--useApplicationTitle` | Override the profile's `suppressApplicationTilte` setting, and set it to `false` | | +| `new-tab`, `nt` | `--colorScheme scheme-name` | Override the profile's `colorScheme` setting, and set it to the scheme from the settings with the name `scheme-name` | The name of a color scheme in the settings | > [!TIP] > If you change the title of a tab in Windows Terminal and want that title to persist, you must enable the [suppressApplicationTitle](./customize-settings/profile-advanced.md#suppress-title-changes) option by setting it to `true`. ### Split-pane command +Used to create a new split pane. See also the [`splitPane` action](./customize-settings/actions.md#split-a-pane). + | Command | Parameter | Description | Values | | ------- | ---------- | ----------- | ------ | | `split-pane`, `sp` | `-H, --horizontal`, `-V, --vertical` | Creates a new split window pane either horizontally or vertically. | N/A. No additional values to assign. | @@ -66,21 +86,54 @@ Below is the full list of supported commands and options for the `wt` command li | `split-pane`, `sp` | `--size, -s size`| Creates a new split window pane with the assigned size. | Float that specifies the portion of the parent pane to use represented by a decimal. For example, `.4` to represent 40% of the parent pane. | | `split-pane`, `sp` | `commandline` | Creates a new split window pane based on the assigned command line. | Executable with optional commands | | `split-pane`, `sp` | `--duplicate, -D` | Creates a new split window pane that is a duplicate of the current pane. | N/A. No additional values to assign. | +| `split-pane`, `sp` | `--suppressApplicationTitle` | Override the profile's `suppressApplicationTilte` setting, and set it to `true` | | +| `split-pane`, `sp` | `--useApplicationTitle` | Override the profile's `suppressApplicationTilte` setting, and set it to `false` | | +| `split-pane`, `sp` | `--colorScheme scheme-name` | Override the profile's `colorScheme` setting, and set it to the scheme from the settings with the name `scheme-name` | The name of a color scheme in the settings | ### Focus-tab command +Used to focus a specific tab within the window. See also the [`switchToTab` action](./customize-settings/actions.md#open-a-specific-tab). + + | Command | Parameter | Description | Values | | ------- | ---------- | ----------- | ------ | | `focus-tab`, `ft` | `--target, -t tab-index` | Focuses on a specific tab according to it's tab index number. | Tab index as an integer | ### Move-focus command +Used to move focus within the window. See also the [`moveFocus` action](./customize-settings/actions.md#move-pane-focus). + | Command | Parameter | Description | Values | | ------- | ---------- | ----------- | ------ | -| `move-focus`, `mf` | `direction` | Move focus between panes in the given direction. | `up`, `down`, `left`, or `right` values accepted. | +| `move-focus`, `mf` | `` | Move focus between panes. | See below for accepted `direction` values | -> [!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`. +Accepted `direction` values +* `up`, `down`, `left`, or `right` move focus in the given direction. +* `first` moves focus to the first leaf pane in the tree. +* `previous` moves the focus to the most recently used pane before the current pane. +* `nextInOrder`, `previousInOrder` moves the focus to the next or previous pane in order of creation. + +### Move-pane command + +Used to move a pane within the window. See also the [`movePane` action](./customize-settings/actions.md#move-pane). + +| Command | Parameter | Description | Values | +| ------- | ---------- | ----------- | ------ | +| `move-pane`, `mp` | `--tab,-t ` | Move the active pane to the given tab in the window | The zero-indexed index of the tab to move the pane to. | + +### Swap-pane command + +Used to swap the position of two panes within the window. See also the [`swapPane` action](./customize-settings/actions.md#swap-panes). + +| Command | Parameter | Description | Values | +| ------- | ---------- | ----------- | ------ | +| `swap-pane` | `` | Swap the pane with the pane in the given direction | See below for accepted `direction` values | + +Accepted `direction` values (these are the same values as the `move-focus` sub command) +* `up`, `down`, `left`, or `right`: Swap the active pane with the one in the given direction. +* `first`: Swap the active pane with the first leaf pane in the tree. +* `previous`: Swap the active pane with the most recently used pane before the current pane. +* `nextInOrder`, `previousInOrder`: Swap the active pane with the next or previous pane in order of creation. ## Command line argument examples diff --git a/TerminalDocs/customize-settings/actions.md b/TerminalDocs/customize-settings/actions.md index c5b2a45c..3c5ab008 100644 --- a/TerminalDocs/customize-settings/actions.md +++ b/TerminalDocs/customize-settings/actions.md @@ -1,9 +1,9 @@ --- title: Windows Terminal Actions description: Learn how to create custom actions for Windows Terminal. -author: cinnamon-msft -ms.author: cinnamon -ms.date: 07/06/2022 +author: nguyen-dows +ms.author: chrnguyen +ms.date: 03/31/2023 ms.topic: how-to --- @@ -678,6 +678,43 @@ ___ ## Pane management commands +### Split a pane + +This halves the size of the active pane and opens another. Without any arguments, this will open the default profile in the new pane. If an action is not specified, the default profile's equivalent setting will be used. + +**Command name:** `splitPane` + +**Default bindings:** + +```json +// In settings.json +{ "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": "up" } }, +{ "command": { "action": "splitPane", "split": "right" } }, +{ "command": { "action": "splitPane", "split": "down" } }, +{ "command": { "action": "splitPane", "split": "left" } } +``` + +#### Parameters + +| Name | Necessity | Accepts | Description | +| ---- | --------- | ------- | ----------- | +| `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) 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. | +| `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. | +| `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`. | + ### Close pane This closes the active pane. If there aren't any split panes, this will close the current tab. If there is only one tab open, this will close the window. @@ -710,7 +747,62 @@ This changes focus to a different pane depending on the direction. Setting the ` | Name | Necessity | Accepts | Description | | ---- | --------- | ------- | ----------- | -| `direction` | Required | `"left"`, `"right"`, `"up"`, `"down"`, `"previous"` | Direction in which the focus will move. | +| `direction` | Required | `"left"`, `"right"`, `"up"`, `"down"`, `"previous"`, `"previousInOrder"`, `"nextInOrder"`, `"first"`, `"parent"`, `"child"` | Direction in which the focus will move. | + +Accepted `direction` values +* `up`, `down`, `left`, or `right` move focus in the given direction. +* `first` moves focus to the first leaf pane in the tree. +* `previous` moves the focus to the most recently used pane before the current pane. +* `nextInOrder`, `previousInOrder` moves the focus to the next or previous pane in order of creation. +* `parent` moves the focus to select the parent pane of the current pane. This enables the user to select multiple panes at once +* `child` moves the focus to the first child pane of this pane. + +### Move pane + +Move the currently active pane to a different tab in the window. + +**Command name:** `movePane` + +**Default bindings:** _(none)_ + +#### Parameters + +| Name | Necessity | Accepts | Description | +| ---- | --------- | ------- | ----------- | +| `index` | Required | number | The zero-indexed index of the tab to move to | + +### Swap panes + +Swap the position of two panes in a tab. This operates on the active pane, and a target pane, as designated by the `direction` parameter. + +**Command name:** `moveFocus` + +**Default bindings:** + +```json +{ "command": { "action": "swapPane", "direction": "down" } }, +{ "command": { "action": "swapPane", "direction": "left" } }, +{ "command": { "action": "swapPane", "direction": "right" } }, +{ "command": { "action": "swapPane", "direction": "up" } }, +{ "command": { "action": "swapPane", "direction": "previous"} }, +{ "command": { "action": "swapPane", "direction": "previousInOrder"} }, +{ "command": { "action": "swapPane", "direction": "nextInOrder"} }, +{ "command": { "action": "swapPane", "direction": "first" } }, +``` + +#### Parameters + +| Name | Necessity | Accepts | Description | +| ---- | --------- | ------- | ----------- | +| `direction` | Required | `"left"`, `"right"`, `"up"`, `"down"`, `"previous"`, `"previousInOrder"`, `"nextInOrder"`, `"first"`, `"parent"`, `"child"` | Direction in which the focus will move. | + +Accepted `direction` values (these are the same values as the `moveFocus` command) +* `up`, `down`, `left`, or `right`: Swap the active pane with the one in the given direction. +* `first`: Swap the active pane with the first leaf pane in the tree. +* `previous`: Swap the active pane with the most recently used pane before the current pane. +* `nextInOrder`, `previousInOrder`: Swap the active pane with the next or previous pane in order of creation. +* `parent`: Does nothing. +* `child`: Does nothing. ### Zoom a pane @@ -851,7 +943,7 @@ This inserts the content that was copied onto the clipboard. { "command": "paste", "keys": "shift+insert" } ``` -### Expand selection to word ([Preview](https://aka.ms/terminal-preview)) +### Expand selection to word If a selection exists, this expands the selection to fully encompass any words partially selected. @@ -875,7 +967,7 @@ This selects all of the content in the text buffer. { "command": "selectAll", "keys": "ctrl+shift+a" } ``` -### Mark mode ([Preview](https://aka.ms/terminal-preview)) +### Mark mode This toggles mark mode. Mark mode is a mode where you can use the keyboard to create a selection at the cursor's position in the terminal. @@ -887,10 +979,7 @@ This toggles mark mode. Mark mode is a mode where you can use the keyboard to cr { "command": "markMode", "keys": "ctrl+shift+m" }, ``` -> [!IMPORTANT] -> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview). - -### Switch selection marker ([Preview](https://aka.ms/terminal-preview)) +### Switch selection marker When modifying a selection using the keyboard, you are moving one end of the selection around. You can use this action to switch to the other selection marker. @@ -902,10 +991,7 @@ When modifying a selection using the keyboard, you are moving one end of the sel { "command": "switchSelectionEndpoint" }, ``` -> [!IMPORTANT] -> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview). - -### Toggle block selection ([Preview](https://aka.ms/terminal-preview)) +### Toggle block selection Makes the exisiting selection a block selection, meaning that the selected area is a rectangle, as opposed to wrapping to the beginning and end of each line. @@ -916,10 +1002,6 @@ Makes the exisiting selection a block selection, meaning that the selected area ```json { "command": "toggleBlockSelection" }, ``` - -> [!IMPORTANT] -> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview). -
___ @@ -1123,7 +1205,7 @@ Changes the active color scheme. { "command": { "action": "setColorScheme", "colorScheme": "Campbell" }, "keys": "" } ``` -### Experimental add scroll mark ([Preview](https://aka.ms/terminal-preview)) +### Experimental add scroll mark Adds a scroll mark to the text buffer. If there's a selection, the mark is placed at the selection, otherwise it's placed at the cursor row. This is an experimental feature, and its continued existence is not guaranteed. @@ -1141,10 +1223,7 @@ Adds a scroll mark to the text buffer. If there's a selection, the mark is place { "command": { "action": "addMark", "color": "#ff00ff" } } ``` -> [!IMPORTANT] -> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview). - -### Experimental scroll to mark ([Preview](https://aka.ms/terminal-preview)) +### Experimental scroll to mark Scrolls to the scroll mark in the given direction. This is an experimental feature, and its continued existence is not guaranteed. @@ -1162,10 +1241,7 @@ Scrolls to the scroll mark in the given direction. This is an experimental featu { "command": { "action": "scrollToMark", "direction": "previous" } } ``` -> [!IMPORTANT] -> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview). - -### Experimental clear mark ([Preview](https://aka.ms/terminal-preview)) +### Experimental clear mark Clears scroll mark at the current position, either at a selection if there is one or at the cursor position. This is an experimental feature, and its continued existence is not guaranteed. @@ -1177,10 +1253,7 @@ Clears scroll mark at the current position, either at a selection if there is on { "command": { "action": "clearMark" } } ``` -> [!IMPORTANT] -> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview). - -### Experimental clear all marks ([Preview](https://aka.ms/terminal-preview)) +### Experimental clear all marks Clears all scroll marks in the text buffer. This is an experimental feature, and its continued existence is not guaranteed. @@ -1191,10 +1264,6 @@ Clears all scroll marks in the text buffer. This is an experimental feature, and ```json { "command": { "action": "clearAllMarks" } } ``` - -> [!IMPORTANT] -> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview). -
___ diff --git a/TerminalDocs/customize-settings/profile-advanced.md b/TerminalDocs/customize-settings/profile-advanced.md index ad615042..11ccdbb4 100644 --- a/TerminalDocs/customize-settings/profile-advanced.md +++ b/TerminalDocs/customize-settings/profile-advanced.md @@ -1,9 +1,9 @@ --- 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: 07/06/2022 +author: nguyen-dows +ms.author: chrnguyen +ms.date: 04/13/2022 ms.topic: how-to --- @@ -88,7 +88,7 @@ ___ ## History size -This sets the number of lines above the ones displayed in the window you can scroll back to. +This sets the number of lines above the ones displayed in the window you can scroll back to. The maximum history size is `32767`. **Property name:** `historySize` diff --git a/TerminalDocs/tutorials/ssh.md b/TerminalDocs/tutorials/ssh.md index 9a9e13cc..c70970c5 100644 --- a/TerminalDocs/tutorials/ssh.md +++ b/TerminalDocs/tutorials/ssh.md @@ -1,9 +1,9 @@ --- title: Windows Terminal SSH description: In this tutorial, learn how to set up an SSH connection in Windows Terminal. -author: cinnamon-msft -ms.author: cinnamon -ms.date: 10/06/2022 +author: nguyen-dows +ms.author: chrnguyen +ms.date: 03/31/2023 ms.topic: tutorial #Customer intent: As a developer or IT admin, I want to set up am SSH connection in Windows Terminal so that I can connect to other servers. --- @@ -20,9 +20,6 @@ By default, the OpenSSH client will be located in the directory: `C:\Windows\Sys ![OpenSSH feature in Windows Settings](../images/ssh-optonialfeatures.png) -> [!NOTE] -> Windows Terminal version 1.XX+ can dynamically generate profiles to connect to the SSH hosts within your [OpenSSH config file](https://man.openbsd.org/ssh_config). - ## Create a profile You can start an SSH session in your command prompt by executing `ssh user@machine` and you will be prompted to enter your password. You can create a Windows Terminal profile that does this on startup by adding the `commandline` setting to a profile in your [settings.json file](../install.md#settings-json-file) inside the `list` of profile objects.