From 55a79ac1bce28e38da9e5b771dfe129d5386f8a9 Mon Sep 17 00:00:00 2001 From: Matt Wojciakowski Date: Tue, 24 Aug 2021 12:37:17 -0700 Subject: [PATCH] Issue resolution updates (#391) * Update to change equal symbol to plus key Addresses issue https://github.com/MicrosoftDocs/terminal/issues/196 *On my Surface Book keyboard + and = are the same key, but this may not be the case for all keyboard layouts. * change + to plus as shipped by default * Add notes about title change persistance * Update settings.json section * Link settings.json mentions * Fix links * fix a few more links * Update TerminalDocs/customize-settings/actions.md Co-authored-by: Kayla Cinnamon * Update TerminalDocs/dynamic-profiles.md Co-authored-by: Kayla Cinnamon * Update TerminalDocs/customize-settings/actions.md Co-authored-by: Kayla Cinnamon * Remove repititious section Co-authored-by: Kayla Cinnamon --- TerminalDocs/command-line-arguments.md | 2 ++ TerminalDocs/command-palette.md | 2 +- .../custom-terminal-gallery/custom-schemes.md | 2 +- TerminalDocs/customize-settings/actions.md | 18 ++++++------- TerminalDocs/customize-settings/appearance.md | 2 +- .../customize-settings/color-schemes.md | 4 +-- .../customize-settings/interaction.md | 2 +- .../customize-settings/profile-advanced.md | 2 +- .../customize-settings/profile-appearance.md | 2 +- .../customize-settings/profile-general.md | 6 ++--- TerminalDocs/customize-settings/rendering.md | 2 +- TerminalDocs/customize-settings/startup.md | 4 +-- TerminalDocs/dynamic-profiles.md | 6 ++--- TerminalDocs/get-started.md | 17 +++++++++--- TerminalDocs/new-terminal-arguments.md | 26 ------------------- TerminalDocs/panes.md | 22 +++++++++++++--- TerminalDocs/search.md | 2 +- TerminalDocs/troubleshooting.md | 10 +++---- TerminalDocs/tutorials/powerline-setup.md | 2 +- TerminalDocs/tutorials/ssh.md | 2 +- 20 files changed, 69 insertions(+), 66 deletions(-) delete mode 100644 TerminalDocs/new-terminal-arguments.md diff --git a/TerminalDocs/command-line-arguments.md b/TerminalDocs/command-line-arguments.md index 4bf89d88..b9ad3295 100644 --- a/TerminalDocs/command-line-arguments.md +++ b/TerminalDocs/command-line-arguments.md @@ -45,6 +45,8 @@ Below is the full list of supported commands and options for the `wt` command li | `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`. | +If you change the title of a tab in Windows Terminal and want that title to persist, you must enable the [suppressApplicationTitle](./customize-settings/actions.md#actions-6) option by setting it to `true`. + > [!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`. diff --git a/TerminalDocs/command-palette.md b/TerminalDocs/command-palette.md index 0e0d5da0..15655a8c 100644 --- a/TerminalDocs/command-palette.md +++ b/TerminalDocs/command-palette.md @@ -34,7 +34,7 @@ You can add a custom key binding for invoking the command palette in the command ## 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. +You can optionally add an icon to a command defined in your [settings.json](./get-started.md#settings-json-file) 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](/windows/uwp/design/style/segoe-ui-symbol-font), or any character, including emojis. ```json { "icon": "C:\\Images\\my-icon.png", "name": "New tab", "command": "newTab", "keys": "ctrl+shift+t" }, diff --git a/TerminalDocs/custom-terminal-gallery/custom-schemes.md b/TerminalDocs/custom-terminal-gallery/custom-schemes.md index cf23fb18..cc93b884 100644 --- a/TerminalDocs/custom-terminal-gallery/custom-schemes.md +++ b/TerminalDocs/custom-terminal-gallery/custom-schemes.md @@ -13,7 +13,7 @@ Here are some color schemes for you to try or use as the basis of your own desig ## Installing schemes -Copy the JSON from the **"schemes"** section into the correct section in settings.json, for example: +Copy the JSON from the **"schemes"** section into the correct section in [settings.json](../get-started.md#settings-json-file), for example: Before: diff --git a/TerminalDocs/customize-settings/actions.md b/TerminalDocs/customize-settings/actions.md index e60b0f2a..f7797f44 100644 --- a/TerminalDocs/customize-settings/actions.md +++ b/TerminalDocs/customize-settings/actions.md @@ -11,7 +11,7 @@ ms.localizationpriority: high # Custom actions in Windows Terminal > [!IMPORTANT] -> As of Windows Terminal version 1.4, the `keybindings` array has been renamed to `actions` inside the settings.json file. Support for the `keybindings` array still exists for backward compatibility, however the terminal will not automatically rename `keybindings` to `actions` inside your settings.json file. +> As of Windows Terminal version 1.4, the `keybindings` array has been renamed to `actions` inside the settings.json file. Support for the `keybindings` array still exists for backward compatibility, however the terminal will not automatically rename `keybindings` to `actions` inside your [settings.json file](../get-started.md#settings-json-file). You can create custom actions inside Windows Terminal that give you control of how you interact with the terminal. These actions will automatically be added to the command palette. @@ -198,7 +198,7 @@ This opens the dropdown menu. ### Open settings files -This opens either the settings UI, custom settings file (`settings.json`), or default settings file (`defaults.json`), depending on the `target` field. +This opens either the settings UI, custom settings file ([`settings.json`](../get-started.md#settings-json-file)), or default settings file (`defaults.json`), depending on the `target` field. Without the `target` field, the custom settings file will be opened. **Command name:** `openSettings` @@ -378,7 +378,7 @@ This creates a new tab. Without any arguments, this will open the default profil | `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. | +| `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. In order to enter a new tab title and have that title persist, this must be set to true. | ### Open next tab @@ -1104,12 +1104,12 @@ ways: The `desktop` and `monitor` properties can be combined in the following ways: -| | `"desktop"` | | | -| -- | --------- | -- | -- | -| **`"monitor"`** | `"any"`
**Leave where it is** | `"toCurrent"`
**Move to current desktop** | `"onCurrent"`
**On current desktop only** | -| `"any"`
**Summon the MRU window** | Go to the desktop the window is on (leave position alone) | Move the window to this desktop (leave position alone) | If there isn't one on this desktop:
  • Create a new one in the default position
Else:
  • Activate the one on this desktop (don't move it)
| -| `"toCurrent"`
**Summon the MRU window TO the monitor with the foreground window** | Go to the desktop the window is on, move to the monitor with the foreground window | Move the window to this desktop, move to the monitor with the foreground window | If there isn't one on this desktop:
  • Create a new one
Else:
  • Activate the one on this desktop, move to the monitor with the foreground window
| -| `"toMouse"`
**Summon the MRU window TO the monitor with the mouse** | Go to the desktop the window is on, move to the monitor with the mouse | Move the window to this desktop, move to the monitor with the mouse | If there isn't one on this desktop:
  • Create a new one
Else:
  • Activate the one on this desktop, move to the monitor with the mouse
| +| Combinations | **`"desktop": "any"`** | **`"desktop": "toCurrent"`**| **`"desktop": "onCurrent"`**| Not included | +| ------------ | ---------------------- | --------------------------- | --------------------------- | ------------ | +| **`"monitor": "any"`**| Go to the desktop the window is on (leave position alone) | Move the window to this desktop (leave position alone) | If there isn't one on this desktop:
  • Create a new one in the default position
Else:
  • Activate the one on this desktop (don't move it)
| Summon the MRU window | +| **`"monitor": "toCurrent"`**| Go to the desktop the window is on, move to the monitor with the foreground window | Move the window to this desktop, move to the monitor with the foreground window | If there isn't one on this desktop:
  • Create a new one
Else:
  • Activate the one on this desktop, move to the monitor with the foreground window
| Summon the MRU window TO the monitor with the foreground window | +| **`"monitor": "toMouse"`**| Go to the desktop the window is on, move to the monitor with the mouse | Move the window to this desktop, move to the monitor with the mouse | If there isn't one on this desktop:
  • Create a new one
Else:
  • Activate the one on this desktop, move to the monitor with the mouse
| Summon the MRU window TO the monitor with the mouse | +| **Not included** | Leave where it is | Move to current desktop | On current desktop only | N/A | #### Examples diff --git a/TerminalDocs/customize-settings/appearance.md b/TerminalDocs/customize-settings/appearance.md index 80d2fabb..a5824b54 100644 --- a/TerminalDocs/customize-settings/appearance.md +++ b/TerminalDocs/customize-settings/appearance.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # Appearance settings in Windows Terminal -The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your settings.json file. +The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your [settings.json file](../get-started.md#settings-json-file). ## Language ([Preview](https://aka.ms/terminal-preview)) diff --git a/TerminalDocs/customize-settings/color-schemes.md b/TerminalDocs/customize-settings/color-schemes.md index fda4c043..5d65b855 100644 --- a/TerminalDocs/customize-settings/color-schemes.md +++ b/TerminalDocs/customize-settings/color-schemes.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # Color schemes in Windows Terminal -Windows Terminal lets you define your own color schemes, either by using the built-in preset schemes, or by creating your own scheme from scratch. To change schemes, you'll need to edit the settings.json file in an editor such as [Visual Studio Code](https://code.visualstudio.com/). +Windows Terminal lets you define your own color schemes, either by using the built-in preset schemes, or by creating your own scheme from scratch. To change schemes, you'll need to edit the [settings.json file](../get-started.md#settings-json-file) in an editor such as [Visual Studio Code](https://code.visualstudio.com/). ## Switching to a different color scheme @@ -39,7 +39,7 @@ Notice the extra comma in the **hidden** line. Once you save this file, Windows The "Tango Light" scheme is included as a default option, but you can create your own scheme from scratch or by copying an existing scheme. -Color schemes can be defined in the `schemes` array of your settings.json file. They are written in the following format: +Color schemes can be defined in the `schemes` array of your [settings.json file](../get-started.md#settings-json-file). They are written in the following format: ```json { diff --git a/TerminalDocs/customize-settings/interaction.md b/TerminalDocs/customize-settings/interaction.md index 67904542..02793856 100644 --- a/TerminalDocs/customize-settings/interaction.md +++ b/TerminalDocs/customize-settings/interaction.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # Interaction settings in Windows Terminal -The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your settings.json file. +The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your [settings.json file](../get-started.md#settings-json-file). ## Automatically copy selection to clipboard diff --git a/TerminalDocs/customize-settings/profile-advanced.md b/TerminalDocs/customize-settings/profile-advanced.md index 8559e7de..f6f27bed 100644 --- a/TerminalDocs/customize-settings/profile-advanced.md +++ b/TerminalDocs/customize-settings/profile-advanced.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # Advanced profile settings in Windows Terminal -The settings listed below are specific to each unique profile. If you'd like a setting to apply to all of your profiles, you can add it to the `defaults` section above the list of profiles in your settings.json file. +The settings listed below are specific to each unique profile. If you'd like a setting to apply to all of your profiles, you can add it to the `defaults` section above the list of profiles in your [settings.json file](../get-started.md#settings-json-file). ```json "defaults": diff --git a/TerminalDocs/customize-settings/profile-appearance.md b/TerminalDocs/customize-settings/profile-appearance.md index 6c5350e4..305298c4 100644 --- a/TerminalDocs/customize-settings/profile-appearance.md +++ b/TerminalDocs/customize-settings/profile-appearance.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # Appearance profile settings in Windows Terminal -The settings listed below are specific to each unique profile. If you'd like a setting to apply to all of your profiles, you can add it to the `defaults` section above the list of profiles in your settings.json file. +The settings listed below affect the visual settings of each profile separately. If you'd like a setting to apply to all of your profiles, you can add it to the `defaults` section above the list of profiles in your [settings.json file](../get-started.md#settings-json-file). ```json "defaults": diff --git a/TerminalDocs/customize-settings/profile-general.md b/TerminalDocs/customize-settings/profile-general.md index 11d77bb9..e8c97636 100644 --- a/TerminalDocs/customize-settings/profile-general.md +++ b/TerminalDocs/customize-settings/profile-general.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # General profile settings in Windows Terminal -The settings listed below are specific to each unique profile. If you'd like a setting to apply to all of your profiles, you can add it to the `defaults` section above the list of profiles in your settings.json file. +The settings listed below are specific to each unique profile. If you'd like a setting to apply to all of your profiles, you can add it to the `defaults` section above the list of profiles in your [settings.json file](../get-started.md#settings-json-file). ```json "defaults": @@ -67,7 +67,7 @@ This is the directory the shell starts in when it is loaded. **Example:** Start the PowerShell profile in the *GitHubRepos* folder of your *Documents* directory by finding the powershell.exe profile and adding `"startingDirectory": "%USERPROFILE%/Documents/GitHubRepos",` -**Example with WSL:** When setting the starting directory for a [Linux distribution installed via WSL](https://docs.microsoft.com/windows/wsl/install-win10), use the format: `"startingDirectory": "\\\\wsl$\\DISTRO NAME\\home\\USERNAME"`, replacing with the placeholders with the proper names of your distribution. For example, `"startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\user1"`. If you are using the Windows Terminal Settings UI, rather than the settings.json file, to declare this path, you can use the **Browse...** button to select your starting directory or enter the WSL path as: `//wsl.localhost/DISTRO NAME/home/USERNAME`. For example, `//wsl.localhost/Ubuntu-20.04/home/user1`. +**Example with WSL:** When setting the starting directory for a [Linux distribution installed via WSL](/windows/wsl/install-win10), use the format: `"startingDirectory": "\\\\wsl$\\DISTRO NAME\\home\\USERNAME"`, replacing with the placeholders with the proper names of your distribution. For example, `"startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\user1"`. If you are using the Windows Terminal Settings UI, rather than the [settings.json file](../get-started.md#settings-json-file), to declare this path, you can use the **Browse...** button to select your starting directory or enter the WSL path as: `//wsl.localhost/DISTRO NAME/home/USERNAME`. For example, `//wsl.localhost/Ubuntu-20.04/home/user1`. **Default behavior:** When the startingDirectory value is not specified, you will get different results depending on where you launch Terminal: - If you run Windows Terminal from the Start menu: C:\windows\system32 @@ -90,7 +90,7 @@ This sets the icon that displays within the tab, dropdown menu, jumplist, and ta **Accepts:** File location as a string, or an emoji -**Example:** By placing the icon image `ubuntu.ico` in the folder located at `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState`, you can display the icon by adding this line to the profile in your settings.json: `"icon": "ms-appdata:///roaming/ubuntu.ico"`. +**Example:** By placing the icon image `ubuntu.ico` in the folder located at `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState`, you can display the icon by adding this line to the profile in your [settings.json](../get-started.md#settings-json-file): `"icon": "ms-appdata:///roaming/ubuntu.ico"`.
___ diff --git a/TerminalDocs/customize-settings/rendering.md b/TerminalDocs/customize-settings/rendering.md index 67753e98..47891512 100644 --- a/TerminalDocs/customize-settings/rendering.md +++ b/TerminalDocs/customize-settings/rendering.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # Rendering settings in Windows Terminal -The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your settings.json file. +The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your [settings.json file](../get-started.md#settings-json-file). If you are thinking about changing the rendering settings, additional information is provided on the [Troubleshooting page](./../troubleshooting.md#the-text-is-blurry) to help guide you. diff --git a/TerminalDocs/customize-settings/startup.md b/TerminalDocs/customize-settings/startup.md index e65ce3d1..0427ff14 100644 --- a/TerminalDocs/customize-settings/startup.md +++ b/TerminalDocs/customize-settings/startup.md @@ -10,7 +10,7 @@ ms.localizationpriority: high # Startup settings in Windows Terminal -The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your settings.json file. +The properties listed below affect the entire terminal window, regardless of the profile settings. These should be placed at the root of your [settings.json file](../get-started.md#settings-json-file). ## Default profile @@ -32,7 +32,7 @@ ___ Set the default terminal emulator in Windows for all command line applications to run inside of. -**Property name:** This modifies an OS setting and does not have a property name inside the settings.json file. +**Property name:** This modifies an OS setting and does not have a property name inside the [settings.json file](../get-started.md#settings-json-file). **Necessity:** Required diff --git a/TerminalDocs/dynamic-profiles.md b/TerminalDocs/dynamic-profiles.md index a03488ff..d037a8ee 100644 --- a/TerminalDocs/dynamic-profiles.md +++ b/TerminalDocs/dynamic-profiles.md @@ -22,13 +22,13 @@ Regardless of whether a new shell is installed before or after your terminal ins ## Hide a profile -To hide a profile from your terminal dropdown menu, add the `hidden` property to the profile object in your settings.json file and set it to `true`. +To hide a profile from your terminal dropdown menu, add the `hidden` property to the profile object in your [settings.json file](./get-started.md#settings-json-file) and set it to `true`. ```json "hidden": true ``` -If you delete a dynamically-created profile, the terminal will automatically regenerate the profile and replace it in your settings.json file. +If you delete a dynamically-created profile, the terminal will automatically regenerate the profile and replace it in your [settings.json file](./get-started.md#settings-json-file). ## Prevent a profile from being generated @@ -40,7 +40,7 @@ To prevent a dynamic profile from being generated, you can add the profile gener ## Add a third party profile -If a 3rd party command line tool does not have a profile auto-generated into your settings.json file, you can add it manually. Below are profiles for a few common 3rd party tools for your reference. +If a 3rd party command line tool does not have a profile auto-generated into your [settings.json file](./get-started.md#settings-json-file), you can add it manually. Below are profiles for a few common 3rd party tools for your reference. ### Anaconda diff --git a/TerminalDocs/get-started.md b/TerminalDocs/get-started.md index 45498768..04938cbe 100644 --- a/TerminalDocs/get-started.md +++ b/TerminalDocs/get-started.md @@ -73,9 +73,20 @@ You can run multiple shells side-by-side using panes. To open a pane, you can us To customize the settings of your Windows Terminal, select **Settings** in the dropdown menu. This will open the settings UI to configure your settings. You can learn how to open the settings UI with keyboard shortcuts on the [Actions page](./customize-settings/actions.md#application-level-commands). -> [!TIP] -> If you prefer to configure your settings by editing a JSON file, select **Settings** in the dropdown menu while holding Shift. This will open the `settings.json` file in your default text editor. (The default text editor is defined in your [Windows settings](ms-settings:defaultapps).) -> The terminal supports customization of global properties that affect the whole application, [profile properties](./customize-settings/profile-general.md) that affect the settings of each profile, and [actions](./customize-settings/actions.md) that allow you to interact with the terminal using your keyboard or the command palette. +### Settings JSON file + +If you prefer to configure your Windows Terminal settings using code, rather than the graphic user interface, you can edit the settings.json file. + +Select **Settings** in the Windows Terminal dropdown menu while holding Shift to open the `settings.json` file in your default text editor. (The default text editor is defined in your [Windows settings](ms-settings:defaultapps).) + +The path for your Windows Terminal settings.json file may be found in one of the following directories: + +- Terminal (stable / general release): `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json` +- Terminal (preview release): `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\settings.json` +- Terminal (unpackaged: Scoop, Chocolately, etc): `%LOCALAPPDATA%\Microsoft\Windows Terminal\settings.json` + +> [!Tip] +> You can access the default settings for Windows Terminal by selecting **Settings** in the dropdown menu while holding Alt to open the `defaults.json` file in your default text editor. This file is auto-generated and any changes to it will be ignored. ## Command line arguments diff --git a/TerminalDocs/new-terminal-arguments.md b/TerminalDocs/new-terminal-arguments.md deleted file mode 100644 index 62635209..00000000 --- a/TerminalDocs/new-terminal-arguments.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: New Terminal Arguments in Windows Terminal -description: New Terminal arguments in Windows Terminal. -author: cinnamon-msft -ms.author: cinnamon -ms.date: 08/26/2020 -ms.topic: include ---- - -### New terminal arguments - -When opening a new pane or tab with a key binding, you can specify which profile is used by including the profile's name, guid, or index. If none are specified, the default profile is used. This can be done by adding `profile` or `index` as an argument to a `splitPane` or `newTab` key binding. Note that indexing starts at 0. - -```json -{ "command": { "action": "splitPane", "split": "vertical", "profile": "profile1" }, "keys": "ctrl+a" }, -{ "command": { "action": "splitPane", "split": "vertical", "profile": "{00000000-0000-0000-0000-000000000000}" }, "keys": "ctrl+b" }, -{ "command": { "action": "newTab", "index": 0 }, "keys": "ctrl+c" } -``` - -Additionally, you can override certain aspects of the profile such as the profile's command line executable, starting directory, or tab title. This can be accomplished by adding `commandline`, `startingDirectory`, and/or `tabTitle` to a `splitPane` or `newTab` key binding. - -```json -{ "command": { "action": "splitPane", "split": "auto", "profile": "profile1", "commandline": "foo.exe" }, "keys": "ctrl+a" }, -{ "command": { "action": "newTab", "profile": "{00000000-0000-0000-0000-000000000000}", "startingDirectory": "C:\\foo" }, "keys": "ctrl+b" }, -{ "command": { "action": "newTab", "index": 0, "tabTitle": "bar", "startingDirectory": "C:\\foo", "commandline": "foo.exe" }, "keys": "ctrl+c" } -``` diff --git a/TerminalDocs/panes.md b/TerminalDocs/panes.md index f1ecac8d..f32078ed 100644 --- a/TerminalDocs/panes.md +++ b/TerminalDocs/panes.md @@ -15,7 +15,7 @@ Panes give you the ability to run multiple command-line applications next to eac ### 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 press the Alt+Shift+= key combination. For a horizontal pane of your default profile, you can use Alt+Shift+-. +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 press the Alt+Shift+plus key combination. For a horizontal pane of your default profile, you can use Alt+Shift+-. ![Windows Terminal create pane](./images/open-panes.gif) _Configuration: [Raspberry Ubuntu](./custom-terminal-gallery/raspberry-ubuntu.md)_ @@ -23,7 +23,7 @@ _Configuration: [Raspberry Ubuntu](./custom-terminal-gallery/raspberry-ubuntu.md If you would like to change these key bindings, you can create new ones using the `splitPane` action and `vertical`, `horizontal`, or `auto` values for the `split` property in your profiles.json file. The `auto` method will choose the direction that gives you the squarest panes. To learn more about key bindings, visit the [Actions page](./customize-settings/actions.md). ```json -{ "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+shift+=" }, +{ "command": { "action": "splitPane", "split": "vertical" }, "keys": "alt+shift+plus" }, { "command": { "action": "splitPane", "split": "horizontal" }, "keys": "alt+shift+-" }, { "command": { "action": "splitPane", "split": "auto" }, "keys": "alt+shift+d" } ``` @@ -114,4 +114,20 @@ You can toggle read-only mode on a pane with the `toggleReadOnlyMode` command. { "command": "toggleReadOnlyMode" }, ``` -[!INCLUDE [new-terminal-arguments](./new-terminal-arguments.md)] +### New terminal arguments + +When opening a new pane or tab with a key binding, you can specify which profile is used by including the profile's name, guid, or index. If none are specified, the default profile is used. This can be done by adding `profile` or `index` as an argument to a `splitPane` or `newTab` key binding. Note that indexing starts at 0. + +```json +{ "command": { "action": "splitPane", "split": "vertical", "profile": "profile1" }, "keys": "ctrl+a" }, +{ "command": { "action": "splitPane", "split": "vertical", "profile": "{00000000-0000-0000-0000-000000000000}" }, "keys": "ctrl+b" }, +{ "command": { "action": "newTab", "index": 0 }, "keys": "ctrl+c" } +``` + +Additionally, you can override certain aspects of the profile such as the profile's command line executable, starting directory, or tab title. This can be accomplished by adding `commandline`, `startingDirectory`, and/or `tabTitle` to a `splitPane` or `newTab` key binding. + +```json +{ "command": { "action": "splitPane", "split": "auto", "profile": "profile1", "commandline": "foo.exe" }, "keys": "ctrl+a" }, +{ "command": { "action": "newTab", "profile": "{00000000-0000-0000-0000-000000000000}", "startingDirectory": "C:\\foo" }, "keys": "ctrl+b" }, +{ "command": { "action": "newTab", "index": 0, "tabTitle": "bar", "startingDirectory": "C:\\foo", "commandline": "foo.exe" }, "keys": "ctrl+c" } +``` diff --git a/TerminalDocs/search.md b/TerminalDocs/search.md index 07fecd26..0f907628 100644 --- a/TerminalDocs/search.md +++ b/TerminalDocs/search.md @@ -38,7 +38,7 @@ The search dialog works with [panes](./panes.md) as well. When focused on a pane ## Customize the search key binding -You can open the search dialog with any key binding (shortcut key combination) that you prefer. To change the search key binding, open your settings.json file and search for the `find` command. By default, this command is set to `ctrl+shift+f`. +You can open the search dialog with any key binding (shortcut key combination) that you prefer. To change the search key binding, open your [settings.json file](./get-started.md#settings-json-file) and search for the `find` command. By default, this command is set to `ctrl+shift+f`. ```json // Press ctrl+shift+f to open the search box diff --git a/TerminalDocs/troubleshooting.md b/TerminalDocs/troubleshooting.md index 5d1b909f..beea917d 100644 --- a/TerminalDocs/troubleshooting.md +++ b/TerminalDocs/troubleshooting.md @@ -37,7 +37,7 @@ For example, the following setting will launch the "Ubuntu-18.04" distribution i ## Setting the tab title -To have the shell automatically set your tab title, [visit the set the tab title tutorial](./tutorials/tab-title.md). If you want to set your own tab title, open the settings.json file and follow these steps: +To have the shell automatically set your tab title, [visit the set the tab title tutorial](./tutorials/tab-title.md). If you want to set your own tab title, open the [settings.json file](./get-started.md#settings-json-file) and follow these steps: 1. In the profile for the command line of your choice, add `"suppressApplicationTitle": true` to suppress any title change events that get sent from the shell. Adding *only* this setting to your profile will set the tab title to the name of your profile. @@ -53,7 +53,7 @@ Visit the [Command line arguments page](./command-line-arguments.md) to learn ho ## Problem setting `startingDirectory` -If the `startingDirectory` is being ignored in your profile, first check to make sure your settings.json's syntax is correct. To help you check this syntax, `"$schema": "https://aka.ms/terminal-profiles-schema"` is automatically injected. Some applications, like [Visual Studio Code](https://code.visualstudio.com/download), can use that injected schema to validate your json file as you make edits. +If the `startingDirectory` is being ignored in your profile, first check to make sure the syntax is correct in your [settings.json file](./get-started.md#settings-json-file). To help you check this syntax, `"$schema": "https://aka.ms/terminal-profiles-schema"` is automatically injected. Some applications, like [Visual Studio Code](https://code.visualstudio.com/download), can use that injected schema to validate your json file as you make edits. If your settings are correct, you may be running a startup script that sets the starting directory of your terminal separately. For example, PowerShell has its own separate concept of profiles. If you are changing your starting directory there, it will take precedence over the setting defined in Windows Terminal. @@ -65,7 +65,7 @@ The purpose of `startingDirectory` is to launch a new Windows Terminal instance By default, Windows Terminal ships with a built-in PowerShell and a Command Prompt profile. The terminal will also autodetect if other command line applications are installed, such as PowerShell Core, WSL distributions (Ubuntu, Debian, etc), and Azure Cloud Shell. We call these types of automatically generated profiles "Dynamic profiles". -For both built-in and dynamic profiles, deleting the profile from your settings.json file will not remove it from your profiles. Built-in profiles are defined in `defaults.json`, so they're always available. Dynamic profiles will attempt to create a JSON stub for their profile in your `settings.json` file whenever a profile is not already present in the file. +For both built-in and dynamic profiles, deleting the profile from your [settings.json file](./get-started.md#settings-json-file) will not remove it from your profiles. Built-in profiles are defined in `defaults.json`, so they're always available. Dynamic profiles will attempt to create a JSON stub for their profile in your `settings.json` file whenever a profile is not already present in the file. The only way to truly remove these profiles from the list is by "hiding" them. To hide a profile, add the property `"hidden": true` to the profile. @@ -79,7 +79,7 @@ If you would like to disable this feature in order for `Ctrl+=` to work properly Change the 'Switch Keyboard Layout' option to 'Not Assigned' (or off of ctrl+shift), then select **OK** and then **Apply**. ctrl+shift+0 should now work as a key binding and is passed through to the terminal. -On the other hand, if you do use this hotkey feature for multiple input languages, you can [configure your own custom key binding](./customize-settings/actions.md) in your settings.json file. +On the other hand, if you do use this hotkey feature for multiple input languages, you can [configure your own custom key binding](./customize-settings/actions.md) in your [settings.json file](./get-started.md#settings-json-file). ## The text is blurry @@ -160,4 +160,4 @@ Press Ctrl + O and Ctrl + X to Save and Exit. ## How do I reset my settings in Windows Terminal back to the default settings? -To reset your settings back to the original default settings, delete your settings.json file. This will cause Windows Terminal to regenerate a settings.json file with the original default settings. +To reset your settings back to the original default settings, delete your [settings.json file](./get-started.md#settings-json-file). This will cause Windows Terminal to regenerate a settings.json file with the original default settings. diff --git a/TerminalDocs/tutorials/powerline-setup.md b/TerminalDocs/tutorials/powerline-setup.md index a98709de..a105e607 100644 --- a/TerminalDocs/tutorials/powerline-setup.md +++ b/TerminalDocs/tutorials/powerline-setup.md @@ -76,7 +76,7 @@ function without the need for additional icons. You can also [create a custom th ### Set Cascadia Code PL as your font -To set the Cascadia Code PL font for use with PowerLine (after [downloading the Cascadia Code font](https://github.com/microsoft/cascadia-code/releases), unzipping, and installing on your system), you will need to open your [profile settings](../customize-settings/profile-appearance.md) in your settings.json file by selecting **Settings** (Ctrl+,) from your Windows Terminal dropdown menu. This can also be done using the settings UI if you have it enabled. +To set the Cascadia Code PL font for use with PowerLine (after [downloading the Cascadia Code font](https://github.com/microsoft/cascadia-code/releases), unzipping, and installing on your system), you will need to open your [profile settings](../customize-settings/profile-appearance.md) in your [settings.json file](../get-started.md#settings-json-file) by selecting **Settings** (Ctrl+,) from your Windows Terminal dropdown menu while holding down Shift. This can also be done using the settings UI if you have it enabled. Once your settings.json file opens, find the Windows PowerShell profile and add: `"fontFace": "Cascadia Code PL"` to designate Cascadia Code PL as the font. This will provide those nice Cascadia Code Powerline glyphs. You should notice the change in your terminal as soon as you select **Save** in your editor. diff --git a/TerminalDocs/tutorials/ssh.md b/TerminalDocs/tutorials/ssh.md index eba36e3a..427334b1 100644 --- a/TerminalDocs/tutorials/ssh.md +++ b/TerminalDocs/tutorials/ssh.md @@ -16,7 +16,7 @@ In this tutorial, you'll learn how to set up a profile in Windows Terminal that ## 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 inside the `list` of profile objects. +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](../get-started.md#settings-json-file) inside the `list` of profile objects. ```json {