diff --git a/TerminalDocs/command-line-arguments.md b/TerminalDocs/command-line-arguments.md index 701ba25b..593e5695 100644 --- a/TerminalDocs/command-line-arguments.md +++ b/TerminalDocs/command-line-arguments.md @@ -20,7 +20,7 @@ You can use `wt.exe` to open a new instance of Windows Terminal from the command The `wt` command line accepts two types of values: **options** and **commands**. **Options** are a list of flags and other parameters that can control the behavior of the `wt` command line as a whole. **Commands** provide the action, or list of actions separated by semicolons, that should be implemented. If no command is specified, then the command is assumed to be `new-tab` by default. -```bash +```cmd wt [options] [command ; ] ``` @@ -61,7 +61,7 @@ To open a new terminal instance, in this case the command will open the profile #### [Command Prompt](#tab/windows) -```bash +```cmd wt -p "Ubuntu-18.04" ``` @@ -91,7 +91,7 @@ To specify the folder that should be used as the starting directory for the cons #### [Command Prompt](#tab/windows) -```bash +```cmd wt -d d:\ ``` @@ -119,7 +119,7 @@ To open a new terminal instance with multiple tabs, enter: #### [Command Prompt](#tab/windows) -```bash +```cmd wt ; ; ``` @@ -147,7 +147,7 @@ To open a new terminal instance with multiple tabs, in this case a Command Promp #### [Command Prompt](#tab/windows) -```bash +```cmd wt -p "Command Prompt" ; new-tab -p "Windows PowerShell" ``` @@ -177,7 +177,7 @@ To open a new terminal instance with one tab containing three panes running a Co #### [Command Prompt](#tab/windows) -```bash +```cmd wt -p "Command Prompt" ; split-pane -p "Windows PowerShell" ; split-pane -H wsl.exe ``` @@ -209,7 +209,7 @@ The `new-tab` and `split-pane` commands can be sequenced to get multiple tabs, e #### [Command Prompt](#tab/windows) -```bash +```cmd wt -p "Command Prompt" ; split-pane -V wsl.exe ; new-tab -d c:\ ; split-pane -H -d c:\ wsl.exe ``` @@ -239,7 +239,7 @@ To open a new terminal instance with custom tab titles, use the `--title` argume #### [Command Prompt](#tab/windows) -```bash +```cmd wt --title tabname1 ; new-tab -p "Ubuntu-18.04" --title tabname2 ``` @@ -267,7 +267,7 @@ To open a new terminal instance with custom tab colors, use the `--tabColor` arg #### [Command Prompt](#tab/windows) -```bash +```cmd wt --tabColor #009999 ; new-tab --tabColor #f59218 ``` @@ -304,7 +304,7 @@ To open a new terminal instance with a specific tab in focus, use the `-t` flag #### [Command Prompt](#tab/windows) -```bash +```cmd wt ; new-tab -p "Ubuntu-18.04" ; focus-tab -t 1 ``` diff --git a/TerminalDocs/customize-settings/interaction.md b/TerminalDocs/customize-settings/interaction.md index 3dbfe627..4b442c26 100644 --- a/TerminalDocs/customize-settings/interaction.md +++ b/TerminalDocs/customize-settings/interaction.md @@ -57,9 +57,13 @@ This determines the word delimiters used in a double-click selection. Word delim **Accepts:** Characters as a string -**Default value:**  /\()"'-:,.;<>~!@#$%^&*|+=[]{}~?│
_(`│` is `U+2502 BOX DRAWINGS LIGHT VERTICAL`)_ +**Default value:** + /\\()\"'-:,.;<>~!@#$%^&*|+=[]{}~?│ +
+_(`│` is `U+2502 BOX DRAWINGS LIGHT VERTICAL`)_ -
+> [!IMPORTANT] +> The following characters must be escaped with a backslash : `\`, `"` ___ diff --git a/TerminalDocs/customize-settings/profile-advanced.md b/TerminalDocs/customize-settings/profile-advanced.md index 2877c354..0d74522f 100644 --- a/TerminalDocs/customize-settings/profile-advanced.md +++ b/TerminalDocs/customize-settings/profile-advanced.md @@ -151,7 +151,8 @@ Profiles can use a GUID as a unique identifier. To make a profile your default p **Accepts:** GUID as a string in registry format: `"{00000000-0000-0000-0000-000000000000}"` -
+> [!TIP] +> You can run `[guid]::NewGuid()` in PowerShell to generate a GUID for your custom profile. ___ diff --git a/TerminalDocs/customize-settings/profile-general.md b/TerminalDocs/customize-settings/profile-general.md index 50d31a51..88463a55 100644 --- a/TerminalDocs/customize-settings/profile-general.md +++ b/TerminalDocs/customize-settings/profile-general.md @@ -68,21 +68,19 @@ This is the directory the shell starts in when it is loaded. **Default value:** `"%USERPROFILE%"` -
+**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",` -> [!NOTE] -> When setting the starting directory that your installed WSL distributions open to, you should use this format: `"startingDirectory": "\\\\wsl$\\DISTRO NAME\\home\\USERNAME"`, replacing with the name of your distribution. For example, `"startingDirectory": "\\\\wsl$\\Ubuntu-20.04\\home\\user1"`. +**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"`. + +**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 +- If you run wt.exe from the Start menu: C:\windows\system32 +- If you run wt.exe from Win+R: %USERPROFILE% +- If you run wt.exe from the explorer address bar: whatever folder you were looking at. > [!NOTE] -> Omitting the startingDirectory value in a profile results in... -
-..if you run Windows Terminal from the Start menu: C:\windows\system32 -
-..if you run wt.exe from the Start menu: C:\windows\system32 -
-..if you run wt.exe from Win+R: %USERPROFILE% -
-..if you run wt.exe from the explorer address bar: whatever folder you were looking at. +> Backslashes need to be escaped. For example, `C:\Users\USERNAME\Documents` should be entered as `C:\\Users\\USERNAME\\Documents`. + ___ ## Icon @@ -95,8 +93,9 @@ This sets the icon that displays within the tab, dropdown menu, jumplist, and ta **Accepts:** File location as a string, or an emoji -
+**Example:** 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"`. +
___ ## Tab title diff --git a/TerminalDocs/get-started.md b/TerminalDocs/get-started.md index b09ca5bd..b9b2e9f6 100644 --- a/TerminalDocs/get-started.md +++ b/TerminalDocs/get-started.md @@ -1,6 +1,6 @@ --- title: Windows Terminal installation -description: In this quickstart, you will learn how to install and run Windows Terminal. +description: In this quickstart, you will learn how to install and set up Windows Terminal. author: cinnamon-msft ms.author: cinnamon ms.date: 01/28/2021 @@ -28,11 +28,17 @@ The terminal will automatically create profiles for you if you have WSL distros ## Open a new tab -You can open a new tab of the default profile by pressing ctrl+shift+t or by selecting the + (plus) button. To open a different profile, select the ˅ (arrow) next to the + button to open the dropdown menu. From there, you can select which profile to open. +You can open a new tab of the default profile by pressing Ctrl+Shift+T or by selecting the + (plus) button. To open a different profile, select the ˅ (arrow) next to the + button to open the dropdown menu. From there, you can select which profile to open. + +## Invoke the command palette + +You can invoke most features of Windows Terminal through the [command palette](./command-palette.md). The default key combination to invoke it is Ctrl+Shift+P. + +![Example of the command palette in use](./images/command-palette-iterable-commands.gif) ## Open a new pane -You can run multiple shells side-by-side using panes. To open a pane, you can use alt+shift+plus for a vertical pane or alt+shift+minus for a horizontal one. You can also use alt+shift+d to open a duplicate pane of your focused profile. Learn more about panes on the [Panes page](./panes.md). +You can run multiple shells side-by-side using panes. To open a pane, you can use Alt+Shift++ for a vertical pane or Alt+Shift+- for a horizontal one. You can also use Alt+Shift+D to open a duplicate pane of your focused profile. Learn more about panes on the [Panes page](./panes.md). ## Configuration diff --git a/TerminalDocs/troubleshooting.md b/TerminalDocs/troubleshooting.md index 0233768e..57afe484 100644 --- a/TerminalDocs/troubleshooting.md +++ b/TerminalDocs/troubleshooting.md @@ -62,6 +62,14 @@ Alternatively, if you are running a script using the `commandline` profile setti The purpose of `startingDirectory` is to launch a new Windows Terminal instance in the given directory. If the terminal runs any code that changes its directory, that may be a good place to take a look. +## Deleting a profile + +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. + +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. + ## Ctrl+= does not increase the font size If you are using a German keyboard layout, you may run into this problem. ctrl+= gets deserialized as ctrl+shift+0 if your main keyboard layout is set to German. This is the correct mapping for German keyboards. diff --git a/TerminalDocs/tutorials/powerline-setup.md b/TerminalDocs/tutorials/powerline-setup.md index e68f3c18..57f41e23 100644 --- a/TerminalDocs/tutorials/powerline-setup.md +++ b/TerminalDocs/tutorials/powerline-setup.md @@ -102,6 +102,13 @@ sudo apt install golang-go go get -u github.com/justjanne/powerline-go ``` +> [!TIP] +> If you're using Ubuntu 18.04 or 16.04, you'll need to first install the correct version of golang: +> ```bash +> sudo add-apt-repository ppa:longsleep/golang-backports +> sudo apt update +> ``` + ### Customize your Ubuntu prompt Open your `~/.bashrc` file with `nano ~/.bashrc` or the text editor of your choice. This is a bash script that runs every time bash starts. Add the following, though beware that GOPATH may already exist: diff --git a/TerminalDocs/tutorials/ssh.md b/TerminalDocs/tutorials/ssh.md index 1cc23329..3afc024b 100644 --- a/TerminalDocs/tutorials/ssh.md +++ b/TerminalDocs/tutorials/ssh.md @@ -16,18 +16,27 @@ 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. +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. -```js -"commandline": "ssh cinnamon@roll" +```json +{ + "name": "user@machine ssh profile", + "commandline": "ssh user@machine", +} ``` +For more information, see: + +* [Windows Terminal Profile - General settings](./../customize-settings/profile-general.md) + ## Specify starting directory To specify the starting directory for a ssh session invoked by Windows Terminal, you can use this command: -```bash -"commandline": "ssh -t bob@foo \"cd /data/bob && exec bash -l\"" +```json +{ + "commandline": "ssh -t bob@foo \"cd /data/bob && exec bash -l\"" +} ``` The `-t` flag forces pseudo-terminal allocation. This can be used to execute arbitrary screen-based programs on a remote machine, e.g. when implementing menu services. You will need to use escaped double quotes as bourne shell derivatives don't do any additional parsing for a string in single quotes. diff --git a/TerminalDocs/tutorials/tab-title.md b/TerminalDocs/tutorials/tab-title.md index cb5d5554..be2629dc 100644 --- a/TerminalDocs/tutorials/tab-title.md +++ b/TerminalDocs/tutorials/tab-title.md @@ -43,7 +43,7 @@ A shell has full control over its own title. However, each shell sets its title | Command Prompt | `TITLE "New Title"` | | bash* | `echo -ne "\033]0;New Title\a"` | -Note that some Linux distributions (i.e. Ubuntu) set their title automatically as you interact with the shell. If the above command doesn't work, run the following command: +Note that some Linux distributions (e.g. Ubuntu) set their title automatically as you interact with the shell. If the above command doesn't work, run the following command: ```bash PS1=$