Merge main to live for Shell Integration & Right-click Context Menu D…

…ocs (#678) * fix(powerline): update oh-my-posh CLI (#632) * Themes updates for 1.17 (#634) Documents a whole pile of stuff from 1.17: * `useMica` microsoft/terminal#13935 * theme pairs microsoft/terminal#14497 * scheme pairs microsoft/terminal#14064 * closes #626 * Default prompt icon info, resolves #625 (#642) * Add app execution alias section (#643) * Add autoHideWindows Resolves #633 * Add color theme FAQs * Remove code brackets from headers Resolves #637 * Fix default if no command specified Called out in #638 * Add note differentiating null from no setting for Starting Directory. Resolves #624 * add the adobe-target metadata for A/B testing (#646) could you please help to merge this metadata change (adobe-target=true) to main branch and then to live? This is to enable A/B testing ability across many url base paths so we can improve Learn user experience based on data-driven decisions. This meta (adobe-target) itself will not change how your content is displayed or modify any other UI behaviors so it is safe to merge. * Add documentation to include information about enable/disable read-only mode functionality (#645) * Update actions to include new enable and disable functionality * Update panes to include new enable and disable functionality * Many updates to commandline args docs, and some missing actions too (#649) * Many updates to commandline args docs, and some missing actions too * Fix anchor link warnings --------- Co-authored-by: Matt Wojciakowski <[email protected]> * Remove Dynamic SSH profiles from doc since it has not been implemente… (#650) * Remove Dynamic SSH profiles from doc since it has not been implemented yet. * Updated authors and date * Shelfing read-only mode docs until it goes in a future release (#653) * Added maximum history size (#657) * added maximum history size * empty commit to poke the bot * remove instances of Preview for 1.15 features (#669) * remove enableReadOnlyMode and disableReadyOnlyMode docs in panes until it goes live in a future release (#672) * Update Docs with Release 1.18 (#674) * Stashed dynamic SSH profiles doc * Add portable mode docs to release branch 1.18 (#655) * added first draft of docs * changed headings and subheadings * Reword, add an Upgrading section --------- Co-authored-by: Dustin Howett <[email protected]> * Retool the portable mode documentation to explain our distributions (#656) * Retool portable mode to be 'distributions' * Fix warnings * add preinstallation to the feature matrix * add dci to matrix * reword * couple more notes * better version note * Use a data matrix table, re-alt-text the portable mode image * add distributions to the toc * address L's feedbacc * Document 'activeOnly' value for 'showCloseButton' property. (#660) * Shelfing read-only mode docs until it goes in a future release (#653) * Added maximum history size (#657) * added maximum history size * empty commit to poke the bot * Document 'activeOnly' value for 'showCloseButton' property. --------- Co-authored-by: Christopher Nguyen <[email protected]> * Add a small section on tab tearout in the overview page (#666) * Shelfing read-only mode docs until it goes in a future release (#653) * Added maximum history size (#657) * added maximum history size * empty commit to poke the bot * initial commit * added preview links and small grammatical fixes * added important preview flag * moved Important flag to the end of the section to fit Actions docs * omit unrelated changes that got pulled in from master * omit actions and profiles changes * Add preview text and re-add missing enableReadOnlyMode docs (#673) * add preview text and readd enableReadOnlyMode that was lost in the most recent commit * add preview text for activeOnly value in showCloseButton property docs --------- Co-authored-by: Dustin Howett <[email protected]> Co-authored-by: kovdu <[email protected]> * Add a tutorial for enabling shell integration (#676) * it's basically just the blog post * fix urls * Right-click context menu, allowHeadless docs (#677) * right-click context menu docs * allowHeadless too while I'm here --------- Co-authored-by: Jan De Dobbeleer <[email protected]> Co-authored-by: Mike Griese <[email protected]> Co-authored-by: Matt Wojciakowski <[email protected]> Co-authored-by: juchen-ms <[email protected]> Co-authored-by: Alex Noble <[email protected]> Co-authored-by: Dustin Howett <[email protected]> Co-authored-by: kovdu <[email protected]>
MicrosoftDocs · May 24, 2023 · 1f2cb5c · 1f2cb5c
1 parent b7e65ad
commit 1f2cb5c
Show file tree

Hide file tree

Showing 3 changed files with 210 additions and 1 deletion.
diff --git a/TerminalDocs/customize-settings/profile-advanced.md b/TerminalDocs/customize-settings/profile-advanced.md
@@ -197,6 +197,27 @@ Enables use of the experimental text rendering engine for the profile. This is a
 
 ___
 
+## Right click context menu ([Preview](https://aka.ms/terminal-preview))
+
+When enabled, right-click will open a context menu with options to copy, paste, and more. When disabled, right-click will paste the contents of the clipboard into the terminal.
+With [shell integration enabled](../tutorials/shell-integration.md), right-click will also allow you to select the current command or output.
+This is an experimental feature, and its continued existence is not guaranteed.
+
+**Property name:** `experimental.rightClickContextMenu`
+
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+<br />
+
+___
+
 ## VT passthrough mode
 
 When set to true, directs the PTY for this connection to use pass-through mode instead of the original Conhost PTY simulation engine. This is an experimental feature, and its continued existence is not guaranteed.

diff --git a/TerminalDocs/customize-settings/startup.md b/TerminalDocs/customize-settings/startup.md
@@ -68,7 +68,7 @@ ___
 
 When set to `"defaultProfile"`, Windows Terminal will start a new session by opening a single tab with your default profile.
 
-When set to `"persistedWindowLayout"`, this enables Windows Terminal to save the layout of open windows on close and restore all saved windows on starting a new session. Windows Terminal will save the layout of all open windows automatically to assist with restoration from crashes and will also save the layout when using the `quit` action. Additionally, closing the last open window by clicking the `X` button or using the `closeWindow` command will save the layout of that last window. 
+When set to `"persistedWindowLayout"`, this enables Windows Terminal to save the layout of open windows on close and restore all saved windows on starting a new session. Windows Terminal will save the layout of all open windows automatically to assist with restoration from crashes and will also save the layout when using the `quit` action. Additionally, closing the last open window by clicking the `X` button or using the `closeWindow` command will save the layout of that last window.
 
 Note: Currently, Windows Terminal will save the following information:
 
@@ -223,3 +223,19 @@ This sets the list of actions to execute on startup, allowing the terminal to la
 **Accepts:** String representing a list of commands to run
 
 **Default value:** `""`
+
+<br />
+
+___
+
+## Continue running in the background ([Preview](https://aka.ms/terminal-preview))
+
+When set to `true`, this enables the terminal to continue running in the background after the last window is closed. This allows [`globalSummon`](./actions.md#global-summon) and [quake mode](../tips-and-tricks.md#quake-mode) to work even when no windows are open. This setting is only available in [Preview](https://aka.ms/terminal-preview) builds of the Terminal.
+
+**Property name:** `compatibility.allowHeadless`
+
+**Necessity:** Optional
+
+**Accepts:** `true`, `false`
+
+**Default value:** `false`
diff --git a/TerminalDocs/tutorials/shell-integration.md b/TerminalDocs/tutorials/shell-integration.md
@@ -0,0 +1,172 @@
+---
+title: Shell integration in the Windows Terminal
+description: In this tutorial, you learn how to configure your shell to enable shell integration features in the Windows Terminal
+author: zadjii-msft
+ms.author: migrie
+ms.date: 05/23/2023
+ms.topic: tutorial
+#Customer intent: As a developer or IT admin, I want to enable shell integration
+---
+
+# Tutorial: Enable shell integration in the Windows Terminal
+
+Starting in Terminal 1.15 Preview, the Windows Terminal has started experimentally supporting some "shell integration" features. These features make the command-line easier to use. In earlier releases, we enabled shell to tell the Terminal what the current working directory is. Now, we've added support for more sequences to allow your shell to semantically describe parts of the terminal output as a "prompt", a "command", or "output". The shell can also tell the terminal whether a command succeeded or failed.
+
+This is a guide to some of the shell integration features we've rolled out as of Terminal v1.18. We're planning on building even more features on top of these in the future, so we'd love to get some additional feedback on how folks using them.
+
+> **Note**:
+>  Notably, "marks" are still experimental, and are **only enabled for [Preview](https://aka.ms/terminal-preview) builds of the Terminal**. The settings for these features may change in a future release.
+
+## How does this work?
+
+Shell integration works by having the shell (or any command line application) write special "escape sequences" to the Terminal. These escape sequences aren't printed to the Terminal - instead, they provide bits of metadata the terminal can use to knwo more about what's going on in the application. By sticking these sequences into your shell's prompt, you can have the shell continuously provide info to the terminal that only the shell knows.
+
+For the following sequences:
+
+* `OSC` is the string `"\x1b]"` - an escape character, followed by `]`
+* `ST` is the "string terminator", and can be either `\x1b\` (an ESC character, followed by `\`) or `\x7` (the BEL character)
+* Spaces are merely illustrative.
+* Strings in `<>` are parameters that should be replaced by some other value.
+
+The relevant supported shell integration sequences as of Terminal v1.18 are:
+
+* `OSC 133 ; A ST` ("_FTCS_PROMPT_") - The start of a prompt.
+* `OSC 133 ; B ST` ("_FTCS_COMMAND_START_") - The start of a commandline (READ: the end of the prompt).
+* `OSC 133 ; C ST` ("_FTCS_COMMAND_EXECUTED_") - The start of the command output / the end of the commandline.
+* `OSC 133 ; D ; <ExitCode> ST` ("_FTCS_COMMAND_FINISHED_") - the end of a command. `ExitCode` If `ExitCode` is provided, then the Terminal will treat `0` as "success" and anything else as an error. If omitted, the terminal will just leave the mark the default color.
+
+## How to enable shell integration marks
+
+Supporting these features requires cooperation between your shell and the Terminal. You'll need to both enable settings in the Terminal to use these new features, as well as modify your shell's prompt.
+
+To enable these features in the Terminal, you'll want to add the following to your settings:
+
+```jsonc
+"profiles":
+{
+    "defaults":
+    {
+        // Marks in general
+        "experimental.showMarksOnScrollbar": true,
+
+        // Needed for both pwsh and CMD shell integration
+        "experimental.autoMarkPrompts": true,
+
+        // Add support for a right-click context menu
+        // You can also just bind the `showContextMenu` action
+        "experimental.rightClickContextMenu": true,
+    },
+}
+"actions":
+[
+    { "keys": "ctrl+up",   "command": { "action": "scrollToMark", "direction": "previous" }, },
+    { "keys": "ctrl+down", "command": { "action": "scrollToMark", "direction": "next" }, },
+
+    // Add the ability to select a whole command (or its output)
+    { "keys": "ctrl+shift+w", "command": { "action": "selectOutput", "direction": "prev" }, },
+    { "keys": "ctrl+shift+s", "command": { "action": "selectOutput", "direction": "next" }, },
+
+    { "keys": "ctrl+alt+shift+w", "command": { "action": "selectCommand", "direction": "prev" }, },
+    { "keys": "ctrl+alt+shift+s", "command": { "action": "selectCommand", "direction": "next" }, },
+]
+```
+
+How you enable these marks in your shell varies from shell to shell. Below are tutorials for CMD and PowerShell.
+
+### PowerShell (`pwsh.exe`)
+
+If you've never changed your PowerShell prompt before, you should check out [about_Prompts](/powershell/module/microsoft.powershell.core/about/about_prompts) first.
+
+We'll need to edit your `prompt` to make sure we tell the Terminal about the CWD, and mark up the prompt with the appropriate marks. PowerShell also lets us include the error code from the previous command in the `133;D` sequence, which will let the terminal automatically colorize the mark based if the command succeeeded or failed.
+
+Add the following to your [PowerShell profile](/powershell/module/microsoft.powershell.core/about/about_profiles):
+
+```pwsh
+$Global:__LastHistoryId = -1
+
+function Global:__Terminal-Get-LastExitCode {
+  if ($? -eq $True) {
+    return 0
+  }
+  if ("$LastExitCode" -ne "") { return $LastExitCode }
+  return -1
+}
+
+function prompt {
+
+  # First, emit a mark for the _end_ of the previous command.
+
+  $gle = $(__Terminal-Get-LastExitCode);
+  $LastHistoryEntry = $(Get-History -Count 1)
+  # Skip finishing the command if the first command has not yet started
+  if ($Global:__LastHistoryId -ne -1) {
+    if ($LastHistoryEntry.Id -eq $Global:__LastHistoryId) {
+      # Don't provide a command line or exit code if there was no history entry (eg. ctrl+c, enter on no command)
+      $out += "`e]133;D`a"
+    } else {
+      $out += "`e]133;D;$gle`a"
+    }
+  }
+
+
+  $loc = $($executionContext.SessionState.Path.CurrentLocation);
+
+  # Prompt started
+  $out += "`e]133;A$([char]07)";
+
+  # CWD
+  $out += "`e]9;9;`"$loc`"$([char]07)";
+
+  # (your prompt here)
+  $out += "PWSH $loc$('>' * ($nestedPromptLevel + 1)) ";
+
+  # Prompt ended, Command started
+  $out += "`e]133;B$([char]07)";
+
+  $Global:__LastHistoryId = $LastHistoryEntry.Id
+
+  return $out
+}
+```
+
+### Command Prompt
+
+Command Prompt sources it's prompt from the `PROMPT` environment variable. CMD.exe reads `$e` as a the `ESC` character.  Unfortunately, CMD.exe doesn't have a way to get the return code of the previous command in the prompt, so we're not able to provide success / error information in CMD prompts.
+
+You can change the prompt for the current CMD.exe instance by running:
+
+```cmd
+PROMPT $e]133;D$e\$e]133;A$e\$e]9;9;$P$e\$P$G$e]133;B$e\
+```
+
+Or, you can set the variable from the commandline for all future sessions:
+
+```cmd
+setx PROMPT $e]133;D$e\$e]133;A$e\$e]9;9;$P$e\$P$G$e]133;B$e\
+```
+
+These examples assume your current `PROMPT` is just `$P$G`. You can instead choose to wrap your current prompt with something like:
+
+```cmd
+PROMPT $e]133;D$e\$e]133;A$e\$e]9;9;$P$e\%PROMPT%$e]133;B$e\
+```
+
+> **Note**:
+> Don't see your favorite shell here? If you figure it out, feel free to [to contribute a solution for your preferred shell!](https://github.com/MicrosoftDocs/terminal/compare)
+
+## Shell integration demos
+
+### Open new tabs in the same working directory
+![Open new tabs in the same working directory](../images/duplicate-tab-same-cwd.gif)
+
+### Show marks for each command in the scrollbar
+![Show marks for each command in the scrollbar](https://user-images.githubusercontent.com/18356694/164290075-a9f0b92c-3dde-4ce3-88cf-da5e451fe46c.gif)
+
+### Automatically jump between commands
+
+![Automatically jump between commands](https://user-images.githubusercontent.com/18356694/164290677-ffaafe09-81c4-4181-a4b8-db79a8aed235.gif)
+
+### Select the entire output of a command
+![Select the entire output of a command](https://user-images.githubusercontent.com/18356694/207696859-a227abe2-ccd4-4b81-8a2c-8a22219cd0dd.gif)
+
+![Select the command using the right-click context menu](https://user-images.githubusercontent.com/18356694/222840120-7a2493b2-2264-4e94-af2b-17bfacc90353.gif)