diff --git a/TerminalDocs/TOC.yml b/TerminalDocs/TOC.yml index c71f8bad..2273807c 100644 --- 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/distributions.md b/TerminalDocs/distributions.md new file mode 100644 index 00000000..03cfd810 --- /dev/null +++ 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/portable-mode.md b/TerminalDocs/portable-mode.md deleted file mode 100644 index 347356a0..00000000 --- a/TerminalDocs/portable-mode.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Windows Terminal Portable Mode -description: Learn how to use Portable mode on Windows Terminal. -author: nguyen-dows -ms.author: chrnguyen -ms.date: 04/10/2023 -ms.topic: how-to ---- - -# Windows Terminal Portable - -As of 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 ("MSIX bundle") distribution of Windows Terminal. - -## Why use Portable mode? - -The unpackaged and portable mode distribution of Windows Terminal allows 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 (and 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](./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 -[unpackaged "ZIP" distribution]: https://github.com/microsoft/terminal/releases