Merge main to live for 1.18 (#675)

* 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]> --------- 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 23, 2023 · b7e65ad · b7e65ad
1 parent 6247f7d
commit b7e65ad
Show file tree

Hide file tree

Showing 10 changed files with 176 additions and 5 deletions.
diff --git a/TerminalDocs/TOC.yml b/TerminalDocs/TOC.yml
@@ -4,6 +4,8 @@
       href: index.md
     - name: Install
       href: install.md
+    - name: Distribution Types
+      href: distributions.md
     - name: Customize settings
       items:
         - name: Startup

diff --git a/TerminalDocs/customize-settings/actions.md b/TerminalDocs/customize-settings/actions.md
@@ -858,6 +858,30 @@ You can mark a pane as read-only, which will prevent input from going into the t
 { "command": "toggleReadOnlyMode" }
 ```
 
+You can enable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `enableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "enableReadOnlyMode" }
+```
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+You can disable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `disableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "disableReadOnlyMode" }
+```
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ### Split a pane
 
 This halves the size of the active pane and opens another. Without any arguments, this will open the default profile in the new pane. If an action is not specified, the default profile's equivalent setting will be used.

diff --git a/TerminalDocs/customize-settings/themes.md b/TerminalDocs/customize-settings/themes.md
@@ -193,12 +193,16 @@ Configures how the "close" button on the tab should appear. This accepts the fol
 * `"always"`: Always show tab close buttons.
 * `"hover"`: Show the tab close button on the active tab, and any tabs that are hovered with the mouse.
 * `"never"`: Never show tab close buttons. This also disables the ability to close the tab with the middle mouse button.
+* `"activeOnly"`: Show the tab close button on the active tab only.
+
+> [!IMPORTANT]
+> The `"activeOnly"` value is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
 **Property name:** `showCloseButton`
 
 **Necessity:** Optional
 
-**Accepts:** `"always"`, `"hover"`, `"never"`
+**Accepts:** `"always"`, `"hover"`, `"never"`, `"activeOnly"`
 
 **Default value:** `"always"`
 

diff --git a/TerminalDocs/distributions.md b/TerminalDocs/distributions.md
@@ -0,0 +1,102 @@
+---
+title: Windows Terminal Distribution Types
+description: Learn how to use the different distributions of Windows Terminal.
+author: nguyen-dows
+ms.author: chrnguyen
+ms.date: 04/10/2023
+ms.topic: how-to 
+---
+
+# Windows Terminal Distribution Types
+
+Windows Terminal is distributed via [GitHub releases] in a variety of formats:
+
+- Packaged, or "MSIX bundle"
+    - This is the oldest and best-supported distribution of Windows Terminal.
+    - The packaged distribution can be installed via the `.msixbundle` file provided on the [GitHub releases] page or
+      through the Microsoft Store ([Stable](https://aka.ms/terminal), [Preview](https://aka.ms/terminal-preview)).
+    - Installation via MSIX bundle may require network connectivity to download dependency packages from the Store.
+    - When installed via MSIX bundle, Terminal will receive automatic updates through the Store.
+- Preinstallation Kit
+    - A [preinstallation kit] is available for system integrators and OEMs interested in preinstalling Windows Terminal
+      on a Windows image.
+    - More information is available in the [DISM documentation on preinstallation]. Users who do not intend to
+      preinstall Windows Terminal should continue using the Packaged distribution.
+    - When installed via preinstallation kit, Terminal will receive automatic updates through the Store.
+- Unpackaged, or "ZIP" (new in 1.17 stable)
+    - This distribution method was not officially supported until stable channel version 1.17.
+    - The unpackaged distribution does not receive automatic updates, which puts you in control of exactly when new
+      versions are installed.
+- Portable
+    - A variant of the unpackaged distribution, where Terminal stores its settings in a nearby directory.
+    - [Learn more about configuring Portable mode.](#windows-terminal-portable)
+
+## Distribution feature comparison
+
+|                                            | Packaged                 | Preinstallation Kit | Unpackaged       | Portable                      |
+| ------------------------------------------ | ------------------------ | ------------------- | ---------------- | ----------------------------- |
+| **Automatic updates**                      | ✅                       | ✅                  | ❌               | ❌                            |
+| **Automatic architecture selection**       | ✅                       | ✅                  | ❌               | ❌                            |
+| **Can be set as your default terminal**    | ✅                       | ✅                  | ❌               | ❌                            |
+| **"Open in Terminal" context menu**        | ✅                       | ✅                  | ❌               | ❌                            |
+| **Automatic start on login option**        | ✅                       | ✅                  | _manual_         | _manual_                      |
+| **Double-click installation**              | ✅                       | ❌                  | ❌               | ❌                            |
+| **Installation on non-networked machines** | ❌                       | ✅                  | ✅               | ✅                            |
+| **Preinstallation in a Windows image**     | ❌                       | ✅                  | _as plain files_ | _as plain files_              |
+| **User-controlled installation path**      | ❌                       | ❌                  | ✅               | ✅                            |
+| **Double-click activatable**               | ❌                       | ❌                  | ✅               | ✅                            |
+| **Settings storage location**              | User folder, per package | (same as packaged)  | `%LOCALAPPDATA%` | Next to `WindowsTerminal.exe` |
+
+## Windows Terminal Portable
+
+As of stable channel version 1.17, Windows Terminal supports being deployed in ["Portable mode"]. Portable mode ensures
+that all data created and maintained by Windows Terminal is saved next to the application so that it can be more easily
+moved across different environments.
+
+Portable mode is supported by the unpackaged "ZIP" distribution.
+
+This is an officially-supported mode of execution where Windows Terminal stores its settings in a `settings` folder next
+to `WindowsTerminal.exe`.
+
+Portable mode is not supported in the packaged or preinstallation kit distributions of Windows Terminal.
+
+### Why use Portable mode?
+
+The unpackaged and portable mode distributions of Windows Terminal allow you to use Terminal without installing it
+globally, e.g. on systems where you may not have permission to install MSIX packages or download software from the
+Microsoft Store.
+
+Portable mode allows you to carry around or archive a preconfigured installation of Windows Terminal and run it from
+a network share, cloud drive or USB flash drive. Any such installation is self-contained and will not interfere with
+other installed distributions of Windows Terminal.
+
+### Enabling Portable mode
+
+Portable mode needs to be enabled manually. After unzipping the Windows Terminal download, create a file named `.portable` next to `WindowsTerminal.exe`.
+
+> [!NOTE]
+> Windows Terminal will not automatically reload its settings when you create the portable mode marker file.
+> This change will only apply after you relaunch Terminal.
+
+Windows Terminal will automatically create a directory named `settings` in which it will store both settings and runtime
+state such as window layouts.
+
+![Windows Terminal portable mode disclaimer example](./images/portable-mode.png)
+
+### Disabling Portable mode
+
+You can restore Portable mode unpackaged installation to its original configuration, where settings are stored in
+`%LOCALAPPDATA%\Microsoft\Windows Terminal`, by removing the `.portable` marker file from the directory containing
+`WindowsTerminal.exe`.
+
+If you wish to reenable portable mode, you can create a new `.portable` marker file next to `WindowsTerminal.exe`.
+
+### Upgrading a Portable mode Install
+
+You can upgrade a portable mode installation of Windows Terminal by moving the `.portable` marker file and the
+`settings` directory to a newly-extracted unpackaged version of Windows Terminal.
+
+["Portable mode"]: https://en.wikipedia.org/wiki/Portable_application
+[GitHub releases]: https://github.com/microsoft/terminal/releases
+[preinstallation kit]: /windows/msix/desktop/deploy-preinstalled-apps
+[DISM documentation on preinstallation]: /windows-hardware/manufacture/desktop/preinstall-apps-using-dism
diff --git a/TerminalDocs/images/attach-tab.gif b/TerminalDocs/images/attach-tab.gif
diff --git a/TerminalDocs/images/portable-mode.png b/TerminalDocs/images/portable-mode.png
diff --git a/TerminalDocs/images/tear-tab.gif b/TerminalDocs/images/tear-tab.gif
diff --git a/TerminalDocs/index.md b/TerminalDocs/index.md
@@ -1,9 +1,9 @@
 ---
 title: An overview on Windows Terminal
 description: Learn about Windows Terminal and how it can improve your command line workflow.
-author: cinnamon-msft
-ms.author: cinnamon
-ms.date: 09/22/2020
+author: nguyen-dows
+ms.author: chrnguyen
+ms.date: 05/17/2023
 ms.topic: overview
 ---
 
@@ -25,6 +25,19 @@ Windows Terminal is a modern host application for the command-line shells you al
 
 Any application that has a command line interface can be run inside Windows Terminal. This includes everything from PowerShell and Command Prompt to Azure Cloud Shell and any WSL distribution such as Ubuntu or Oh-My-Zsh.
 
+## Tab tearout ([Preview](https://aka.ms/terminal-preview))
+
+You can tear out tabs in Windows Terminal and create new windows.
+
+![Windows Terminal tab tearout](./images/tear-tab.gif)
+
+You can also drag and drop tabs into existing windows.
+
+![Dragging and dropping tabs into Terminal windows](./images/attach-tab.gif)
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ## Customized schemes and configurations
 
 You can configure your Windows Terminal to have a variety of color schemes and settings. To learn how to customize your prompt with cool themes, see [Tutorial: Set up a custom prompt for PowerShell or WSL with Oh My Posh](./tutorials/custom-prompt-setup.md) To learn how to make your own color scheme, visit the [Color schemes page](./customize-settings/color-schemes.md).

diff --git a/TerminalDocs/panes.md b/TerminalDocs/panes.md
@@ -224,6 +224,32 @@ You can toggle read-only mode on a pane with the `toggleReadOnlyMode` command.
 { "command": "toggleReadOnlyMode" }
 ```
 
+You can enable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `enableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "enableReadOnlyMode" }
+```
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+You can disable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `disableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "disableReadOnlyMode" }
+```
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ## Customizing panes using key bindings
 
 You can customize what opens inside a new pane depending on your custom key bindings.

diff --git a/TerminalDocs/tutorials/ssh.md b/TerminalDocs/tutorials/ssh.md
@@ -10,7 +10,7 @@ ms.topic: tutorial
 
 # Tutorial: SSH in Windows Terminal
 
-Windows has a built-in SSH client that you can use in Windows Terminal. In this tutorial, you'll learn how to set up a profile in Windows Terminal that uses SSH.
+Windows has a built-in SSH client that you can use in Windows Terminal. In this tutorial, you'll learn how to set up a profile in Windows Terminal that uses SSH. Note that this feature is in preview.
 
 ## Access Windows SSH Client