Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merge main to live for 1.18 #675

Merged
merged 19 commits into from
May 23, 2023
Merged

Merge main to live for 1.18 #675

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
e24e293
fix(powerline): update oh-my-posh CLI (#632)
JanDeDobbeleer Jan 19, 2023
4a4f34f
Themes updates for 1.17 (#634)
zadjii-msft Jan 25, 2023
94f98ac
Default prompt icon info, resolves https://github.com/MicrosoftDocs/t…
mattwojo Mar 10, 2023
462e28c
Add app execution alias section (#643)
mattwojo Mar 10, 2023
a75242b
Add autoHideWindows
mattwojo Mar 10, 2023
6072685
Add color theme FAQs
mattwojo Mar 11, 2023
7e63707
Remove code brackets from headers
mattwojo Mar 11, 2023
a97d323
Fix default if no command specified
mattwojo Mar 11, 2023
5c72b7e
Add note differentiating null from no setting
mattwojo Mar 11, 2023
9c7fc3b
add the adobe-target metadata for A/B testing (#646)
partychen Mar 21, 2023
fa43e33
Add documentation to include information about enable/disable read-on…
Swinkid Mar 31, 2023
e23a454
Many updates to commandline args docs, and some missing actions too (…
zadjii-msft Mar 31, 2023
3c54de8
Remove Dynamic SSH profiles from doc since it has not been implemente…
nguyen-dows Mar 31, 2023
b37bacf
Shelfing read-only mode docs until it goes in a future release (#653)
nguyen-dows Apr 10, 2023
0f63f98
Added maximum history size (#657)
nguyen-dows Apr 19, 2023
3d3b3c0
remove instances of Preview for 1.15 features (#669)
nguyen-dows May 17, 2023
8e0f365
remove enableReadOnlyMode and disableReadyOnlyMode docs in panes unti…
nguyen-dows May 19, 2023
888f793
Merge branch 'live' into main
nguyen-dows May 19, 2023
1bf834a
Update Docs with Release 1.18 (#674)
nguyen-dows May 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions TerminalDocs/TOC.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
href: index.md
- name: Install
href: install.md
- name: Distribution Types
href: distributions.md
- name: Customize settings
items:
- name: Startup
Expand Down
75 changes: 64 additions & 11 deletions TerminalDocs/command-line-arguments.md
View file
Open in desktop
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
163 changes: 128 additions & 35 deletions TerminalDocs/customize-settings/actions.md
View file
Open in desktop
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 @@ -766,6 +858,30 @@ You can mark a pane as read-only, which will prevent input from going into the t
{ "command": "toggleReadOnlyMode" }
```

You can enable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.

**Command name:** `enableReadOnlyMode`

**Default bindings:**

```json
{ "command": "enableReadOnlyMode" }
```
> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).

You can disable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.

**Command name:** `disableReadOnlyMode`

**Default bindings:**

```json
{ "command": "disableReadOnlyMode" }
```
> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).

### 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.
Expand Down Expand Up @@ -851,7 +967,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 +991,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 +1003,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 +1015,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 +1026,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 +1229,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 +1247,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 +1265,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 +1277,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 +1288,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
Loading