Skip to content

Commit

Permalink
Merge Main to Live (#670)
Browse files Browse the repository at this point in the history 
* fix(powerline): update oh-my-posh CLI (#632)

* Themes updates for 1.17 (#634)

Documents a whole pile of stuff from 1.17:

* `useMica` microsoft/terminal#13935
* theme pairs microsoft/terminal#14497
* scheme pairs microsoft/terminal#14064
* closes #626

* Default prompt icon info, resolves #625 (#642)

* Add app execution alias section (#643)

* Add autoHideWindows

Resolves #633

* Add color theme FAQs

* Remove code brackets from headers

Resolves #637

* Fix default if no command specified

Called out in #638

* Add note differentiating null from no setting 

for Starting Directory. 
Resolves #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 <mattwoj@microsoft.com>

* 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 <migrie@microsoft.com>
Co-authored-by: Matt Wojciakowski <mattwoj@microsoft.com>
Co-authored-by: juchen-ms <partychen.acm@gmail.com>
Co-authored-by: Alex Noble <6237394+Swinkid@users.noreply.github.com>
  • Loading branch information
@nguyen-dows @JanDeDobbeleer
@zadjii-msft @mattwojo @partychen @Swinkid
6 people authored May 19, 2023
1 parent 5fa1855 commit 6247f7d
Show file tree
Hide file tree
Showing 4 changed files with 175 additions and 56 deletions.
75 changes: 64 additions & 11 deletions TerminalDocs/command-line-arguments.md
View file
Original file line number Diff line number Diff line change
@@ -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
---

Expand Down Expand Up @@ -35,27 +35,47 @@ 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` `<window-id>` | 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 |
| `new-tab`, `nt` | `--startingDirectory, -d starting-directory` | Creates a new tab based on the starting directory path assigned. | Directory path |
| `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. |
Expand All @@ -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` | `<direction>` | 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 <index>` | 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` | `<direction>` | 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

Expand Down
139 changes: 104 additions & 35 deletions TerminalDocs/customize-settings/actions.md
View file
Original file line number Diff line number Diff line change
@@ -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
---

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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).
<br />

___
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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).
<br />

___
Expand Down
8 changes: 4 additions & 4 deletions TerminalDocs/customize-settings/profile-advanced.md
View file
Original file line number Diff line number Diff line change
@@ -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
---

Expand Down Expand Up @@ -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`

Expand Down
Loading

0 comments on commit 6247f7d

Please sign in to comment.