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.

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

Add Windows Terminal Preview release 1.1 features #64

Merged
merged 19 commits into from
Jun 17, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@
href: panes.md
- name: Cascadia Code
href: cascadia-code.md
- name: Tips and tricks
href: tips-and-tricks.md
- name: Tutorials
items:
- name: Powerline setup
Expand Down
45 changes: 42 additions & 3 deletions TerminalDocs/command-line-arguments.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: 05/19/2020
ms.date: 06/18/2020
ms.topic: how-to
ms.service: terminal
---
Expand Down Expand Up @@ -34,13 +34,21 @@ 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. |

> [!IMPORTANT]
> `--maximized`, `-M` and `--fullscreen`, `-F` are only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

| Command | Parameters | Description |
| ------- | ---------- | ----------- |
| `new-tab` | `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline` | Creates a new tab. |
| `split-pane` | `-H, --horizontal`, `-V, --vertical`, `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline` | Splits a new pane. |
| `new-tab` | `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline`, `--title` | Creates a new tab. |
| `split-pane` | `-H, --horizontal`, `-V, --vertical`, `--profile, -p profile-name`, `--startingDirectory, -d starting-directory`, `commandline`, `--title` | Splits a new pane. |
| `focus-tab` | `--target, -t tab-index` | Focuses on a specific tab. |

> [!IMPORTANT]
> `--title` is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

## Command line argument examples

Commands may vary slightly depending on which command line you're using.
Expand Down Expand Up @@ -193,6 +201,37 @@ Execution aliases do not work in WSL distributions. If you want to use wt.exe fr

The `-H` flag (or `--horizontal`) indicates that you would like the panes to be split horizontally. The `-V` flag (or `--vertical`) indicates that you would like the panes split vertically.

### Tab title ([Preview](https://aka.ms/terminal-preview/))

To open a new terminal instance with custom tab titles, use the `--title` argument. To set the title of each tab when opening two tabs, enter:

<!-- Start tab selectors. -->
#### [Command Prompt](#tab/windows)

```bash
wt --title tabname1 ; new-tab -p "Ubuntu-18.04" --title tabname2
```

#### [PowerShell](#tab/powershell)

```powershell
wt --title tabname1 `; new-tab -p "Ubuntu-18.04" --title tabname2
```

#### [Linux](#tab/linux)

```bash
cmd.exe /c "wt.exe" --title tabname1 \; new-tab -p "Ubuntu-18.04" --title tabname2
```

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 the `\;` forward-slash + semicolon separates commands.

---
<!-- End tab selectors. -->

> [!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:
Expand Down
38 changes: 31 additions & 7 deletions TerminalDocs/customize-settings/global-settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Windows Terminal Global Settings
description: Learn how to customize the global settings within Windows Terminal.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 05/19/2020
ms.date: 06/18/2020
ms.topic: how-to
ms.service: terminal
ms.localizationpriority: high
Expand All @@ -21,10 +21,13 @@ Set the default profile that opens by typing <kbd>ctrl+shift+t</kbd>, typing the

**Necessity:** Required

**Accepts:** GUID as a string
**Accepts:** GUID or profile name as a string

**Default value:** PowerShell's GUID

> [!IMPORTANT]
> Using the profile name for `defaultProfile` is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

<br />

___
Expand Down Expand Up @@ -98,13 +101,13 @@ When this is set to `true`, tabs are always displayed. When it's set to `false`

:::row:::
:::column span="":::
This sets the width of the tabs. `"equal"` makes each tab the same width. `"titleLength"` sizes each tab to the length of its title.
This sets the width of the tabs. `"equal"` makes each tab the same width. `"titleLength"` sizes each tab to the length of its title. `"compact"` will shrink every inactive tab to the width of the icon, leaving the active tab more space to display its full title.

**Property name:** `tabWidthMode`

**Necessity:** Optional

**Accepts:** `"equal"`, `"titleLength"`
**Accepts:** `"equal"`, `"titleLength"`, `"compact"`

**Default value:** `"equal"`

Expand All @@ -115,6 +118,9 @@ This sets the width of the tabs. `"equal"` makes each tab the same width. `"titl
:::column-end:::
:::row-end:::

> [!IMPORTANT]
> The `"compact"` setting is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

### Hide close all tabs popup

:::row:::
Expand Down Expand Up @@ -142,18 +148,36 @@ ___

## Launch settings

### Launch maximized
### Launch on startup ([Preview](https://aka.ms/terminal-preview/))

When set to `true`, this enables the launch of Windows Terminal at startup. Setting this to `false` will disable the startup task entry. Note: if the Windows Terminal startup task entry is disabled either by org policy or by user action this setting will have no effect.

**Property name:** `startOnUserLogin`

This defines whether the terminal will launch as maximized to fill the entire screen or in a window.
**Necessity:** Optional

**Accepts:** `true`, `false`

**Default value:** `false`

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

### Launch size

This defines whether the terminal will launch as maximized, fullscreen, or in a window.

**Property name:** `launchMode`

**Necessity:** Optional

**Accepts:** `"default"`, `"maximized"`
**Accepts:** `"default"`, `"maximized"`, `"fullscreen"`

**Default value:** `"default"`

> [!IMPORTANT]
> The `"fullscreen"` setting is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

### Launch position

This sets the pixel position of the top left corner of the window upon first load. On a system with multiple displays, these coordinates are relative to the top left of the primary display. If an X or Y coordinate is not provided, the terminal will use the system default for that value. If `launchMode` is set to `"maximized"`, the window will be maximized on the monitor specified by those coordinates.
Expand Down
18 changes: 14 additions & 4 deletions TerminalDocs/customize-settings/key-bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Windows Terminal Key Bindings
description: Learn how to create custom key bindings for Windows Terminal.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 05/19/2020
ms.date: 06/18/2020
ms.topic: how-to
ms.service: terminal
ms.localizationpriority: high
Expand Down Expand Up @@ -150,18 +150,28 @@ This opens the dropdown menu.
{ "command": "openNewTabDropdown", "keys": "ctrl+shift+space" }
```

### Open settings file
### Open settings files

This opens the settings file.
This opens either the default or custom settings files. Without the `target` field, this will open the settings.json file.

**Command name:** `openSettings`

**Default binding:**

```json
{ "command": "openSettings", "keys": "ctrl+," }
{ "command": "openSettings", "keys": "ctrl+," },
{ "command": { "action": "openSettings", "target": "defaultsFile" }, "keys": "ctrl+alt+," },
```

#### Actions

| Name | Necessity | Accepts | Description |
| ---- | --------- | ------- | ----------- |
| `target` | Optional | `"settingsFile"`, `"defaultsFile"`, `"allFiles"` | The settings file to open. |

> [!IMPORTANT]
> The `target` field is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

### Toggle full screen

This allows you to switch between full screen and default window sizes.
Expand Down
38 changes: 37 additions & 1 deletion TerminalDocs/customize-settings/profile-settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Windows Terminal Profile Settings
description: Learn how to customize the individual profiles within Windows Terminal.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 05/19/2020
ms.date: 06/18/2020
ms.topic: how-to
ms.service: terminal
ms.localizationpriority: high
Expand Down Expand Up @@ -171,6 +171,21 @@ This sets the profile's font size in points.

**Default value:** `12`

### Font weight ([Preview](https://aka.ms/terminal-preview/))

This sets the weight (lightness or heaviness of the strokes) for the profile's font.

**Property name:** `fontWeight`

**Necessity:** Optional

**Accepts:** `"normal"`, `"thin"`, `"extra-light"`, `"light"`, `"semi-light"`, `"medium"`, `"semi-bold"`, `"bold"`, `"extra-bold"`, `"black"`, `"extra-black"`, or an integer corresponding to the numeric representation of the OpenType font weight

**Default value:** `"normal"`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you planning on including examples?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wasn't planning on it until weights come in for Cascadia?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean, there are other fonts that exist :) haha


> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

### Padding

:::row:::
Expand Down Expand Up @@ -248,6 +263,27 @@ This sets the percentage height of the cursor starting from the bottom. This wil

___

## Keyboard settings

### AltGr aliasing ([Preview](https://aka.ms/terminal-preview/))

This allows you to control if Windows Terminal will treat <kbd>ctrl+alt</kbd> as an alias for <kbd>AltGr</kbd>.
cinnamon-msft marked this conversation as resolved.
Show resolved Hide resolved

**Property name:** `altGrAliasing`

**Necessity:** Optional

**Accepts:** `true`, `false`

**Default value:** `true`

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

<br />

___

## Color settings

### Color scheme
Expand Down
1 change: 1 addition & 0 deletions TerminalDocs/docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
{
"files": [
"**/*.png",
"**/*.gif",
"**/*.jpg"
],
"exclude": [
Expand Down
Binary file added TerminalDocs/images/alt-click-pane.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added TerminalDocs/images/tab-color.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added TerminalDocs/images/tab-rename.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified TerminalDocs/images/tab-width-mode.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 12 additions & 1 deletion TerminalDocs/panes.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Windows Terminal Panes
description: Learn how to split panes in the Windows Terminal.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 05/19/2020
ms.date: 06/18/2020
ms.topic: how-to
ms.service: terminal
---
Expand All @@ -14,6 +14,8 @@ Panes give you the ability to run multiple command-line applications next to eac

## Creating a new pane

### Using the keyboard

You can either create a new vertical or horizontal pane in Windows Terminal. Splitting vertically will open a new pane to the right of the focused pane and splitting horizontally will open a new pane below the focused pane. To create a new vertical pane of your default profile, you can type <kbd>alt+shift+plus</kbd>. For a horizontal pane of your default profile, you can type <kbd>alt+shift+-</kbd>.

![Windows Terminal create pane](./images/open-panes.gif)
Expand All @@ -27,6 +29,15 @@ If you would like to change these key bindings, you can create new ones using th
{ "command": { "action": "splitPane", "split": "auto" }, "keys": "alt+shift+|" }
```

### Using the dropdown menu ([Preview](https://aka.ms/terminal-preview/))

If you'd like to open a new pane through the dropdown menu, you can hold <kbd>alt</kbd> and click on your desired profile. This will `auto` split the active window or pane into a new pane of the selected profile. The `auto` split mode splits in the direction that has the longest edge to create a pane.

![Windows Terminal dropdown pane](./images/alt-click-pane.gif)

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

## Switching between panes

The terminal allows you to navigate between panes by using the keyboard. If you hold the <kbd>alt</kbd> key, you can use your arrow keys to move your focus between panes. You can identify which pane is in focus by the accent color border surrounding it. Note that this accent color is set in your Windows color settings.
Expand Down
41 changes: 41 additions & 0 deletions TerminalDocs/tips-and-tricks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: Windows Terminal tips and tricks
description: In this page, you will find tips and tricks to help improve your Windows Terminal experience.
author: cinnamon-msft
ms.author: cinnamon
ms.date: 06/18/2020
ms.topic: how-to
ms.service: terminal
ms.localizationpriority: high
---

# Windows Terminal tips and tricks

## Rename a tab ([Preview](https://aka.ms/terminal-preview/))

You can right click on a tab and select Rename Tab to rename a tab for that terminal session. Clicking this option in the context menu will change your tab title into a text field, where you can then edit the title. If you'd like to set the tab title for that profile for every terminal instance, you can learn more in the [Tab title tutorial](./tutorials/tab-title.md).

![Windows Terminal tab rename](./images/tab-rename.gif)

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

## Color a tab ([Preview](https://aka.ms/terminal-preview/))

You can right click on a tab and select Color... to color the tab for that terminal session. You can select from a predefined list of colors or you can click Custom... to pick any color using the color picker or the RGB/HSV or hex fields.

![Windows Terminal tab color](./images/tab-color.png)

> [!TIP]
> Use the hex field to set your tab to the same color as your background color for a seamless look.

> [!IMPORTANT]
> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview/).

## Zoom with the mouse

You can zoom the text window of Windows Terminal by holding <kbd>ctrl</kbd> and scrolling. The zoom will persist for that terminal session. If you want to change your font size, you can learn more about the font size feature on the [Profile settings page](./customize-settings/profile-settings#text-settings).

## Adjust background opacity with the mouse

You can adjust the opacity of the background by holding <kbd>ctrl+shift</kbd> and scrolling. The opacity will persist for that terminal session. If you want to change your acrylic opacity for a profile, you can learn more about acrylic background effects on the [Profile settings page](./customize-settings/profile-settings#acrylic-settings)