diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index a7471495..db113773 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -23,7 +23,7 @@ "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": {}, @@ -31,7 +31,7 @@ { "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" } -} +} \ No newline at end of file diff --git a/TerminalDocs/TOC.yml b/TerminalDocs/TOC.yml index fee76966..99e2d7ba 100644 --- 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 index b83fb59b..9ceda390 100644 --- 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 alt 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 index 04ed9fe1..4ccbf14b 100644 --- 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": `, `"centerOnLaunch": true`, `"launchMode": "default"`: center on the default monitor. -* `"initialPos": `, `"centerOnLaunch": true`, `"launchMode": "focus"`: center and enter focus mode on the default monitor. -* `"initialPos": `, `"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": `, `"centerOnLaunch": true`, `"launchMode": "default"`: center on the default monitor. +* `"initialPosition": `, `"centerOnLaunch": true`, `"launchMode": "focus"`: center and enter focus mode on the default monitor. +* `"initialPosition": `, `"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 new file mode 100644 index 00000000..4ce85770 --- /dev/null +++ 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 \ No newline at end of file diff --git a/TerminalDocs/images/admin-mode.png b/TerminalDocs/images/admin-mode.png new file mode 100644 index 00000000..42f5e314 Binary files /dev/null and b/TerminalDocs/images/admin-mode.png differ diff --git a/TerminalDocs/images/file-issue.png b/TerminalDocs/images/file-issue.png new file mode 100644 index 00000000..92c0015e Binary files /dev/null and b/TerminalDocs/images/file-issue.png differ diff --git a/TerminalDocs/images/settings-add-profile.png b/TerminalDocs/images/settings-add-profile.png new file mode 100644 index 00000000..58b259cb Binary files /dev/null and b/TerminalDocs/images/settings-add-profile.png differ diff --git a/TerminalDocs/images/settings-batch-file.png b/TerminalDocs/images/settings-batch-file.png new file mode 100644 index 00000000..e0093701 Binary files /dev/null and b/TerminalDocs/images/settings-batch-file.png differ diff --git a/TerminalDocs/images/terminalretro.png b/TerminalDocs/images/terminalretro.png new file mode 100644 index 00000000..65346391 Binary files /dev/null and b/TerminalDocs/images/terminalretro.png differ diff --git a/TerminalDocs/install.md b/TerminalDocs/install.md index 7a7a637a..2dbd3c36 100644 --- 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 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. +> 1. 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. +> 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 index 260d0242..a0eef516 100644 --- 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\\AppData\Local\Microsoft\Windows Terminal\Fragments\{file-name}.json` +`C:\Users\\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 index 8f7de021..5c72d00f 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. 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 Alt+Shift+plus 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. 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 Alt+Shift++ 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)_ @@ -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 Ctrl+Shift+P by default. + This can be done by using the `togglePaneZoom` command. ```json diff --git a/TerminalDocs/samples.md b/TerminalDocs/samples.md new file mode 100644 index 00000000..254a66d9 --- /dev/null +++ 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). diff --git a/TerminalDocs/tutorials/custom-prompt-setup.md b/TerminalDocs/tutorials/custom-prompt-setup.md index 6fef32dd..553a7ac5 100644 --- a/TerminalDocs/tutorials/custom-prompt-setup.md +++ b/TerminalDocs/tutorials/custom-prompt-setup.md @@ -102,8 +102,7 @@ If you would like to use Oh My Posh to style both Windows and Windows Subsystem For PowerShell, open your profile file with `notepad $PROFILE` and add the following: ```powershell - oh-my-posh --init --shell pwsh --config ~/jandedobbeleer.omp.json | Invoke-Expression - Set-PoshPrompt -Theme jandedobbeleer + oh-my-posh --init --shell pwsh --config ~/AppData/Local/Programs/oh-my-posh/themes/jandedobbeleer.omp.json | Invoke-Expression ``` Once added, reload your profile for the changes to take effect.