Main > Live (#448)

* Update to change equal symbol to plus key Addresses issue #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 <[email protected]> * Update TerminalDocs/dynamic-profiles.md Co-authored-by: Kayla Cinnamon <[email protected]> * Update TerminalDocs/customize-settings/actions.md Co-authored-by: Kayla Cinnamon <[email protected]> * Remove repititious section * Added browser media keys (#371) * Add link to what is command line shell video (#377) * add intenseTextStyle to the docs (#381) * Multiple new pane features (#383) Documentation for - microsoft/terminal#10713 - microsoft/terminal#10638 - microsoft/terminal#10780 - microsoft/terminal#10927 * wt.exe --window argument now available (#388) * Add notes that the `font` object is only 1.10+ (#389) Co-authored-by: Kayla Cinnamon <[email protected]> * Remove MinimizeToTray action mentions (#387) * Docs updates for 1.11 release (#397) * Specify OS version availability for defterm (#417) Co-authored-by: Kayla Cinnamon <[email protected]> * Remove tilde Reshttps://github.com/MicrosoftDocs/terminal/issues/260olves * Improve dup tab description #292 * Update minimizetotray setting to new name * Merge release 1.12 into master (#428) Co-authored-by: Kayla Cinnamon <[email protected]> Co-authored-by: Pankaj Bhojwani <[email protected]> Co-authored-by: Matt Wojciakowski <[email protected]> Co-authored-by: Mike Griese <[email protected]> Co-authored-by: Carlos Zamora <[email protected]> Co-authored-by: Schuyler Rosefield <[email protected]> Co-authored-by: PankajBhojwani <[email protected]> * Remove preview labels * Add redirect for old powerline page * Add vscode to gitignore * Config changes to reflect the default branch from master to main. * Add a note about the command palette to this doc (#447) * Add details about the command used to print the table (#446) * initialPos -> initialPosition (#445) * Add tip on extensions for configuration files (#440) * Add tip on extensions for configuration files Resolves #423 * fix numbering Co-authored-by: Matt Wojciakowski <[email protected]> * Corrected path (#434) The LocalAppData path was missing `{app-name}` * Update panes.md (#432) Minor edit on a shortcut key * Correct $PROFILE configuration (#431) When using winget, Oh-my-posh will not add Set-PoshPrompt to path, the execution will fail. The correct configuration can be found in https://ohmyposh.dev/docs/windows#replace-your-existing-prompt * Add a sample page (#444) * Add FAQ page (#442) * Add FAQ page * Finalize faq v1 * Replace md with yml, add toc * Update with settings UI feedback from kayla * fix image link * Fix preview faq Co-authored-by: Kayla Cinnamon <[email protected]> Co-authored-by: Floris Westerman <[email protected]> Co-authored-by: Mike Griese <[email protected]> Co-authored-by: Schuyler Rosefield <[email protected]> Co-authored-by: Sean Jacobs <[email protected]> Co-authored-by: Leon Liang <[email protected]> Co-authored-by: Carlos Zamora <[email protected]> Co-authored-by: Pankaj Bhojwani <[email protected]> Co-authored-by: PankajBhojwani <[email protected]> Co-authored-by: Nivaldo Tokuda <[email protected]> Co-authored-by: David A. Sjøen <[email protected]> Co-authored-by: tharindu sathischandra <[email protected]> Co-authored-by: Cutano <[email protected]>
MicrosoftDocs · Nov 22, 2021 · b56dd2f · b56dd2f
1 parent c815280
commit b56dd2f
Show file tree

Hide file tree

Showing 15 changed files with 184 additions and 13 deletions.
diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json
@@ -23,15 +23,15 @@
   "sync_notification_subscribers": [],
   "branches_to_filter": [],
   "git_repository_url_open_to_public_contributors": "https://github.com/MicrosoftDocs/terminal",
-  "git_repository_branch_open_to_public_contributors": "master",
+  "git_repository_branch_open_to_public_contributors": "main",
   "skip_source_output_uploading": false,
   "need_preview_pull_request": true,
   "contribution_branch_mappings": {},
   "dependent_repositories": [
     {
       "path_to_root": "_themes",
       "url": "https://github.com/Microsoft/templates.docs.msft",
-      "branch": "master",
+      "branch": "main",
       "branch_mapping": {}
     }
   ],
@@ -40,4 +40,4 @@
   "docs_build_engine": {
     "name": "docfx_v3"
   }
-}
+}
diff --git a/TerminalDocs/TOC.yml b/TerminalDocs/TOC.yml
@@ -60,6 +60,10 @@
           href: custom-terminal-gallery/frosted-glass-theme.md
         - name: Retro Command Prompt
           href: custom-terminal-gallery/retro-command-prompt.md
+    - name: FAQs
+      href: faq.yml
+    - name: Samples
+      href: samples.md
     - name: Troubleshooting
       href: troubleshooting.md
 

diff --git a/TerminalDocs/customize-settings/color-schemes.md b/TerminalDocs/customize-settings/color-schemes.md
@@ -80,6 +80,9 @@ ___
 
 Windows Terminal includes these color schemes inside the defaults.json file, which can be accessed by holding <kbd>alt</kbd> and selecting the settings button. Color schemes can **not** be changed in the defaults.json file. For a color scheme to apply across all profiles, change it in the [defaults section of your settings.json file](./profile-general.md).
 
+> [!NOTE]
+> You can print the current color scheme to the Terminal using [`colortool`](https://github.com/microsoft/terminal/tree/main/src/tools/ColorTool), with the commandline `colortool -c`
+
 
 ### Campbell
 

diff --git a/TerminalDocs/customize-settings/startup.md b/TerminalDocs/customize-settings/startup.md
@@ -180,11 +180,11 @@ When set to `true`, the terminal window will auto-center itself on the display i
 
 This interacts with the other launch settings in the following ways:
 
-* `"initialPos": x,y`, `"centerOnLaunch": true`, `"launchMode": "default"`: center on the monitor that `x,y` is on.
-* `"initialPos": x,y`, `"centerOnLaunch": true`, `"launchMode": "maximized"`: maximized on the monitor that `x,y` is on (`centerOnLaunch` adds nothing).
-* `"initialPos": <omitted>`, `"centerOnLaunch": true`, `"launchMode": "default"`: center on the default monitor.
-* `"initialPos": <omitted>`, `"centerOnLaunch": true`, `"launchMode": "focus"`: center and enter focus mode on the default monitor.
-* `"initialPos": <omitted>`, `"centerOnLaunch": true`, `"launchMode": "maximized"`: maximized on the default monitor (`centerOnLaunch` adds nothing).
+* `"initialPosition": x,y`, `"centerOnLaunch": true`, `"launchMode": "default"`: center on the monitor that `x,y` is on.
+* `"initialPosition": x,y`, `"centerOnLaunch": true`, `"launchMode": "maximized"`: maximized on the monitor that `x,y` is on (`centerOnLaunch` adds nothing).
+* `"initialPosition": <omitted>`, `"centerOnLaunch": true`, `"launchMode": "default"`: center on the default monitor.
+* `"initialPosition": <omitted>`, `"centerOnLaunch": true`, `"launchMode": "focus"`: center and enter focus mode on the default monitor.
+* `"initialPosition": <omitted>`, `"centerOnLaunch": true`, `"launchMode": "maximized"`: maximized on the default monitor (`centerOnLaunch` adds nothing).
 
 **Property name:** `centerOnLaunch`
 

diff --git a/TerminalDocs/faq.yml b/TerminalDocs/faq.yml
@@ -0,0 +1,99 @@
+### YamlMime:FAQ
+metadata:
+  title: Windows Terminal FAQ
+  description: Frequently asked questions about Windows Terminal, such as how to start terminal in administrator mode, how to save a terminal session, and more.
+  ms.topic: troubleshooting
+  ms.date: 11/15/2021
+  ms.author: mattwoj
+  author: mattwojo
+  manager: jken
+  ms.reviewer: cinnamon
+
+title: Windows Terminal FAQ
+summary: |
+  Find answers to some of the most frequently asked questions about Windows Terminal.
+
+sections:
+  - name: General
+    questions:
+      - question: How do I run a shell in Windows Terminal in administrator mode?
+        answer: |
+          To run Windows Terminal with elevated administrator permission (admin mode), right-click on the Windows Terminal icon, then again on the Windows Terminal title that displays, then select "Run as administrator".
+
+          ![Windows Terminal admin mode](./images/admin-mode.png)
+          
+          Alternatively, you can open the Windows Quick Access menu using the shortcut, ⊞ Windows key + X, and then selecting Windows Terminal (Admin).
+
+      - question: Is it possible to mix admin and non-admin tabs in a Windows Terminal window?
+        answer: |
+          No, mixing administrator-level permission tabbed shells with those that do not have elevated administrator permission is not supported due to security concerns.
+
+      - question: Can I use Windows Terminal as the integrated terminal in VSCode?
+        answer: |
+          No, Visual Studio Code is xtermjs and written in TypeScript while Windows Terminal is native code.
+
+      - question: What shells does Windows Terminal support?
+        answer: |
+          Windows Terminal will support any command line or shell that you have on your machine, including those that are included with Windows like PowerShell or Windows Command Prompt (cmd.exe), as well as any Linux distribution that can be installed with [WSL](/windows/wsl/), Azure Cloud Shell, Git Bash, etc. The terminal will automatically detect when you've installed a Linux distribution with WSL and create a profile for you. It can also save your Azure credentials, so you can quickly log in quickly to Azure Cloud Shell.
+
+      - question: How can I manually add a shell?
+        answer: |
+          In your [settings.json file](./install.md#settings-json-file), you can create or modify profiles that run any command-line executable. In the settings.json file, set "commandline" to whatever you want. For example, powershell --> "pwsh.exe".
+          You can also add a profile using the terminal settings ui by scrolling to the bottom of your profiles list and selecting "+ Add a new profile".
+          ![Screenshot of settings add a profile](./images/settings-add-profile.png)
+
+      - question: What is the difference between Windows Terminal and Windows Terminal (Preview)?
+        answer: |
+          [Windows Terminal](https://www.microsoft.com/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab) is the stable public release and receives regular updates that have been tested and debugged in the preview release. The recommended way to [install](./install.md) is via the Microsoft Store, which will provide automatic updates whenever they are released.
+          [Windows Terminal Preview](https://www.microsoft.com/p/windows-terminal-preview/9n8g5rfz9xk3#activetab=pivot:overviewtab) is a release for those interested in trying the latest features as they are being developed, tested for bugs, and becoming stable enough to be added to the main terminal release. Features from this release are documented with the (Preview) tag.
+
+      - question: What alternative ways are there to install Windows Terminal?
+        answer: |
+          While we recommend installing Windows Terminal [using the Microsoft Store](https://www.microsoft.com/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab), you can also install using [Windows Package Manager](https://github.com/Microsoft/terminal#via-windows-package-manager-cli-aka-winget), [GitHub](https://github.com/Microsoft/terminal#via-github), [Chocolatey](https://github.com/Microsoft/terminal#via-chocolatey-unofficial), or [Scoop](https://github.com/Microsoft/terminal#via-scoop-unofficial).
+
+      - question: Is it possible to initialize a Windows Terminal profile with a batch file?
+        answer: |
+          Yes. You first need to go to the [Profiles](./customize-settings/profile-general.md) section of your [settings.json file](./install.md#settings-json-file). Using the [`"commandline":` property](./customize-settings/profile-general.md#command-line), you can specify any batch file, command, ssh connection, or executable that you want to run as a profile in Windows Terminal. You just need to enter the path to the file that you want to run.
+
+          This example shows an example of a terminal profile set up based on a "demo" batch file.
+
+          ```json
+          {
+          "commandline": "%USERPROFILE%/OneDrive/demo.bat",
+          "name": "Batch Profile"
+          }
+          ```
+          This can also be done in the Settings UI. Select "+ Add a new profile" > "+ New empty profile". Browse to the starting directory where your batch file (or SSH connection, executable, command file, etc) is located. Give the profile a name and save.
+          ![Screenshot of settings add an batch file profile](./images/settings-batch-file.png)
+
+      - question: What sort of features have open-source community contributors added to Windows Terminal?
+        answer: |
+          There have been a wide variety of [contributions](https://github.com/microsoft/terminal/pulls?q=is%3Apr+is%3Aclosed) to Windows Terminal, including bug fixes, identifying and discussing [issues](https://github.com/microsoft/terminal/issues), [contributing to this documentation](/contribute/), but a few of our favorite features that have come from community contributions have included support for [background images and gifs](./customize-settings/profile-appearance.md#background-images-and-icons), [retro effects](./customize-settings/profile-appearance.md#retro-terminal-effects), and [tab coloring](./customize-settings/profile-appearance.md#tab-color), just to name a few. Learn more about [how to contribute](https://github.com/microsoft/terminal/blob/main/CONTRIBUTING.md).
+
+      - question: What is conhost.exe?
+        answer: |
+          The Windows Console host, conhost.exe, is Windows' original command-line user experience. It also hosts Windows' command-line infrastructure and the Windows Console API server, input engine, rendering engine, user preferences, etc. A primary goal of Windows Console is to maintain backward compatibility, thus adding new features became prohibitive and let to the creation of the Windows Terminal. Learn more in the [Windows Terminal open-source repo](https://github.com/Microsoft/terminal#the-windows-console-host) and in the [WIndows Console docs](/windows/console/definitions#console-host).
+
+      - question: Can I save the layout of all of my open console windows when closing Windows Terminal and restore them when starting a new session?
+        answer: |
+          Yes! As of [Windows Terminal Preview v1.12.2922.0](https://github.com/microsoft/terminal/releases/tag/v1.12.2922.0), you can now save window pane layouts upon closing a terminal session with the [firstWindowPreference](./customize-settings/startup.md#behavior-when-starting-a-new-terminal-session-preview) global setting.
+
+      - question: What is being planned for Windows Terminal? Is there a development roadmap or feature request list that I can contribute to?
+        answer: |
+          Windows Terminal is under very active development. You can view the team's plans on the [Terminal 2.0 Roadmap](https://github.com/microsoft/terminal/blob/main/doc/terminal-v2-roadmap.md) document in the open-source terminal repo. New features go into [Windows Terminal Preview](https://aka.ms/terminal-preview) first, then typically a month after they've been in Preview, those features move into [Windows Terminal](https://aka.ms/terminal).
+
+          You can contribute feature Requests or ideas, as well as bug reports, security vulnerabilities, or documentation issues by [filing an issue in the terminal repo](https://github.com/microsoft/terminal/issues/new/choose).
+
+          ![Screenshot of filing an issue in terminal repo](./images/file-issue.png)
+
+      # - question: Is there a way to sync your terminal settings across devices?
+      #   answer: |
+      #     TBD
+
+      # - question: Can we expect a status bar on the bottom of Windows Terminal? 
+      #   answer: |
+      #     TBD
+
+      # - question: TBD
+      #   answer: |
+      #     TBD
diff --git a/TerminalDocs/images/admin-mode.png b/TerminalDocs/images/admin-mode.png
diff --git a/TerminalDocs/images/file-issue.png b/TerminalDocs/images/file-issue.png
diff --git a/TerminalDocs/images/settings-add-profile.png b/TerminalDocs/images/settings-add-profile.png
diff --git a/TerminalDocs/images/settings-batch-file.png b/TerminalDocs/images/settings-batch-file.png
diff --git a/TerminalDocs/images/terminalretro.png b/TerminalDocs/images/terminalretro.png
diff --git a/TerminalDocs/install.md b/TerminalDocs/install.md
@@ -86,7 +86,8 @@ The path for your Windows Terminal settings.json file may be found in one of the
 - 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 <kbd>Alt</kbd> to open the `defaults.json` file in your default text editor. This file is auto-generated and any changes to it will be ignored.
+> 1. You can access the default settings for Windows Terminal by selecting  **Settings** in the dropdown menu while holding <kbd>Alt</kbd> to open the `defaults.json` file in your default text editor. This file is auto-generated and any changes to it will be ignored.
+> 2. It is possible to create a [JSON fragment extension](./json-fragment-extensions.md) in order to store profile data and color schemes in a separate file, which can be useful to prevent excessively large configuration files.
 
 ## Command line arguments
 

diff --git a/TerminalDocs/json-fragment-extensions.md b/TerminalDocs/json-fragment-extensions.md
@@ -130,6 +130,6 @@ The first is that the installation is for all the users on the system. In this c
 
 In the second case, the installation is only for the current user. In this case, the JSON files should be added to the folder:
 
-`C:\Users\<user>\AppData\Local\Microsoft\Windows Terminal\Fragments\{file-name}.json`
+`C:\Users\<user>\AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json`
 
 Note that both the `ProgramData` and `LocalAppData` folders are known folders that the installer should be able to access. If in either case, if the `Windows Terminal\Fragments` directory does not exist, the installer should create it. The `{app-name}` should be unique to your application and the `{file-name}.json` can be anything - the terminal will read all .json files in that directory.
diff --git 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. Using directional splits `up`, `right`, `down`, or `left` gives more options for where the new pane can go. `right` and `down` are equivalent to `vertical` and `horizontal`, whereas `up` and `left` allow you to put the new pane above and to the left of the focused pane respectively. To create a new vertical pane of your default profile, you can press the <kbd>Alt</kbd>+<kbd>Shift</kbd>+plus key combination. For a horizontal pane of your default profile, you can use <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>-</kbd>.
+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. Using directional splits `up`, `right`, `down`, or `left` gives more options for where the new pane can go. `right` and `down` are equivalent to `vertical` and `horizontal`, whereas `up` and `left` allow you to put the new pane above and to the left of the focused pane respectively. To create a new vertical pane of your default profile, you can press the <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>+</kbd> key combination. For a horizontal pane of your default profile, you can use <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>-</kbd>.
 
 ![Windows Terminal create pane](./images/open-panes.gif)
 _Configuration: [Raspberry Ubuntu](./custom-terminal-gallery/raspberry-ubuntu.md)_
@@ -201,6 +201,10 @@ You can zoom the focused pane to fill the entire contents of the window.
 
 ![Windows Terminal toggle pane zoom](./images/toggle-pane-zoom.gif)
 
+
+> [!NOTE]
+> The menu in the above gif is the [Command Palette](./command-palette.md), which can be opened with <kbd>Ctrl+Shift+P</kbd> by default.
+
 This can be done by using the `togglePaneZoom` command.
 
 ```json

diff --git a/TerminalDocs/samples.md b/TerminalDocs/samples.md
@@ -0,0 +1,61 @@
+---
+title: Windows Terminal sample code
+description: Windows Terminal sample code, including Pixel Shader .hlsl samples, an EchoCon ConPTY sample Win32 pseudo console, a GUIConsole sample WPF console targeting .NET, a MiniTerm sample using basic PTY API calls, and a ReadConsoleInputStream demo for monitoring of console events while streaming character input.
+author: cinnamon-msft
+ms.author: cinnamon
+ms.date: 11/16/2021
+ms.topic: samples
+ms.localizationpriority: medium
+---
+
+# Windows Terminal sample code
+
+Explore some of the sample code hosted on the Windows Terminal repo, including [Pixel Shader .hlsl samples](#pixel-shaders), an [EchoCon ConPTY sample Win32 pseudo console](#echocon-conpty-sample-app), a [GUIConsole sample WPF console targeting .NET](#guiconsole-sample-app), a [MiniTerm sample using basic PTY API calls](#miniterm-sample-app), and a [ReadConsoleInputStream demo](#readconsoleinputstream-demo) for monitoring of console events while streaming character input.
+
+## Pixel Shaders
+
+Due to the sheer amount of computing power in GPUs, one can do awesome things with pixel shaders such as real-time fractal zoom, ray tracers and image processing.
+
+Windows Terminal allows users to provide a pixel shader, applied to the terminal by adding the `experimental.pixelShaderPath` property to a profile in your settings.json file. Pixel shaders are written in a language called [HLSL](https://github.com/microsoft/terminal/tree/main/samples/PixelShaders#hlsl), a C-like language with some restrictions.
+
+Try one of several Pixel Shader .hlsl samples provided in the Windows Terminal repo: [Pixel Shaders](https://github.com/microsoft/terminal/tree/main/samples/PixelShaders).
+
+![Terminal Retro Pixel Shader sample](./images/terminalretro.png)
+
+## EchoCon ConPTY sample app
+
+This sample application illustrates how to use the Win32 Pseudo Console (ConPTY) by:
+
+1. Creating an input and an output pipe
+2. Calling CreatePseudoConsole() to create a ConPTY instance attached to the other end of the pipes
+3. Spawning an instance of ping.exe connected to the ConPTY
+4. Running a thread that listens for output from ping.exe, writing received text to the Console
+
+Visit the Windows Terminal repo to find this sample: [EchoCon ConPTY Sample App](https://github.com/microsoft/terminal/tree/main/samples/ConPTY/EchoCon).
+
+## GUIConsole sample app
+
+This sample application provides an example skeleton of a custom [WPF](/dotnet/desktop/wpf/overview/) console.
+
+Within this sample, you will find:
+
+- GUIConsole.WPF: a WPF application, targeting .NET 4.6.1, that creates a single WPF window which acts as the console and keeps the underlying console visible.
+
+- GUIConsole.ConPTY: a .NET Standard 2.0 library that handles the creation of the console and enables pseudoconsole behavior. The Terminal.cs file contains the publicly visible pieces that the WPF application will interact with. Terminal.cs exposes two things that allow reading from, and writing to, the console:
+
+  - `ConsoleOutStream`: a FileStream hooked up to the pseudoconsole's output pipe. This will output VT100.
+  - `WriteToPseudoConsole`(string input): a method that will take the given string and write it to the pseudoconsole via its input pipe. This accepts VT100.
+
+Visit the Windows Terminal repo to find this sample: [GUIConsole](https://github.com/microsoft/terminal/tree/main/samples/ConPTY/GUIConsole).
+
+## MiniTerm sample app
+
+This experimental terminal demonstrates basic API calls (not intended for "real-world" usage) using [PTY APIs](/windows/console/creating-a-pseudoconsole-session) from Microsoft. Written in C# and heavily based on the native code examples.
+
+Visit the Windows Terminal repo to find this sample: [MiniTerm](https://github.com/microsoft/terminal/tree/main/samples/ConPTY/MiniTerm).
+
+## ReadConsoleInputStream Demo
+
+Demonstration of asynchronous monitoring of console events (like mouse, menu, focus, buffer/viewport resize) while simultaneously streaming the character input view from the console. A particularly useful feature when working with VT100 streams and ConPTY.
+
+Visit the Windows Terminal repo to find this demo: [ReadConsoleInputStream Demo](https://github.com/microsoft/terminal/tree/main/samples/ReadConsoleInputStream).