commit bf0f199c1b93e38c7bdfeafe3a436f63a11fc3ef parent 9773b2f1cc272108233815ba7170e37554d9d61f Author: Kevin Larkin (MS) <kevinla@microsoft.com> Date: Mon, 10 May 2021 09:01:40 -0700 Update Windows Package Manager commands (#939) * Baseline docs * fixed typo * add terms * Update winget commands * Add gif to exclude * Fixed spelling errors and added to exception list Diffstat:
26 files changed, 565 insertions(+), 1 deletion(-)
diff --git a/.github/actions/spelling/excludes.txt b/.github/actions/spelling/excludes.txt @@ -2,6 +2,7 @@ (?:^|/)(?i)LICENSE /shared\.manifest$ \.cer$ +\.gif$ \.msix$ \.png$ \.vcxitems$ diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt @@ -25,6 +25,7 @@ AUrl Aysnc azurewebsites Baz +bcp Beigi bfd bght @@ -205,6 +206,7 @@ pvm pwabuilder PWAs PWSTR +px pz qb qword diff --git a/doc/windows/package-manager/package/windows-package-manager-policies.md b/doc/windows/package-manager/package/windows-package-manager-policies.md @@ -0,0 +1,24 @@ +# Windows Package Manager Repository Policies + +**Document version: 1.0** + +**Document date: May 22, 2021** + +**Effective date: May 22, 2021** + +Thank you for your interest in providing a product to the Windows Package Manager repository. + +"Product" means content in whatever form including, but not limited to, apps, games, titles, and any additional content sold or offered from within a Product. +"Submission" means Pull Request of manifest files and includes but is not limited to the product and metadata about the product. + +Coming soon ... + + +--- + +### See also + +- [Change history for Windows Package Manager Policy History](windows-package-manager-policies-change-history.md) +- [Windows Package Manager Code of Conduct](https://github.com/microsoft/winget-pkgs/blob/master/CODE_OF_CONDUCT.md) +- [Windows Package Manager Contributing requirements](https://github.com/microsoft/winget-pkgs/blob/master/README.md) + + \ No newline at end of file diff --git a/doc/windows/package-manager/winget/export.md b/doc/windows/package-manager/winget/export.md @@ -0,0 +1,60 @@ +--- +title: export Command +description: exports the list of installed applications. +ms.date: 05/02/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# export command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **export** command of the [winget](index.md) tool exports a JSON file of apps to a specified file. The **export** command users JSON as the format. The JSON schema used by **winget** can be found [here](https://aka.ms/winget-packages.schema.1.0.json). + +The **export** combined with the [**import**](.\import.md) command allows you to batch install applications on your PC. + +The **export** command is often used to create a file that you can share with other developers, or for use when restoring your build environment. + +## Usage + +`winget export [-o] <output> [<options>]` + + + +## Arguments + +The following arguments are available. +| Argument | Description | +|-------------|-------------| +| **-o,--output** | Path to the JSON file to be created + +## Options + +The options allow you to customize the export experience to meet your needs. + +|<div style="width:290px">Option</div> | Description | +|----------------|-------------| +| **-s, --source** | [optional] Specifies a source to export files from. Use this option when you only want files from a specific source. | +| **--include-versions** | [optional] Includes the version of the app currently installed. Use this option if you want a specific version. By default, unless specified, [**import**](.\import.md) will use latest. | + +## JSON Schema +The driving force behind the **export** command is the JSON file. As mentioned, you can find the schema for the JSON file [here](https://aka.ms/winget-packages.schema.1.0.json). + +The JSON file includes the following hierarchy: +| Entry | Description | +|-------------|-------------| +| **Sources** | The repo that the the application is installed from. | +| **Packages** | The collection of packages to install. | +| **Id** | The Windows Package Manager id used to identify the package. | +| **Version** | [optional] The specific version of the package to install. | + +## exporting files + +When the Windows Package Manager exports the JSON file, it attempts to export all the applications installed on the PC. If the **winget export** command is not able to match an application to an application from an available **source**, the export command will show a warning. + +In the example below, you will see warnings for _reSearch_ and _Angry Birds_. + + + +Once the export is complete, you can edit the resulting JSON file in your favorite editor. You can remove apps you do not wish to import in the future. diff --git a/doc/windows/package-manager/winget/features.md b/doc/windows/package-manager/winget/features.md @@ -0,0 +1,27 @@ +--- +title: features Command +description: Displays the list of experimental features available and the state. +ms.date: 05/5/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# features command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **features** command of the [winget](index.md) tool displays a list of the experimental features available with you version of the Windows Package Manager. + +Each feature can be turned on individually by enabling the features through [**settings**](.\settings.md). + +You can find the latest up to date information features on the [experimental features](https://aka.ms/winget-experimentalfeatures) web page. + +## Usage + +`winget features` + + + +Notice above that the status of each feature is listed. If the feature is **disabled** you will not be able to use it. If the feature is **enabled** you will notice that the command will be available to you through winget. + +To enabled disabled features, go to **settings** and enable the feature. diff --git a/doc/windows/package-manager/winget/images/export-command.png b/doc/windows/package-manager/winget/images/export-command.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/export.png b/doc/windows/package-manager/winget/images/export.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/features.png b/doc/windows/package-manager/winget/images/features.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/import-command.png b/doc/windows/package-manager/winget/images/import-command.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/import.png b/doc/windows/package-manager/winget/images/import.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/list-count.png b/doc/windows/package-manager/winget/images/list-count.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/list-update.png b/doc/windows/package-manager/winget/images/list-update.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/list.png b/doc/windows/package-manager/winget/images/list.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/settings.png b/doc/windows/package-manager/winget/images/settings.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/uninstall-execute.png b/doc/windows/package-manager/winget/images/uninstall-execute.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/uninstall-multiple.png b/doc/windows/package-manager/winget/images/uninstall-multiple.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/uninstall-with-list.png b/doc/windows/package-manager/winget/images/uninstall-with-list.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/uninstall.png b/doc/windows/package-manager/winget/images/uninstall.png Binary files differ. diff --git a/doc/windows/package-manager/winget/images/upgrade.gif b/doc/windows/package-manager/winget/images/upgrade.gif Binary files differ. diff --git a/doc/windows/package-manager/winget/images/upgrade.png b/doc/windows/package-manager/winget/images/upgrade.png Binary files differ. diff --git a/doc/windows/package-manager/winget/import.md b/doc/windows/package-manager/winget/import.md @@ -0,0 +1,56 @@ +--- +title: import Command +description: imports the list of installed applications. +ms.date: 05/02/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# import command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **import** command of the [winget](index.md) tool imports a JSON file of apps to install. The **import** command combined with the [**export**](.\export.md) command allows you to batch install applications on your PC. + +The **import** command is often used to share your developer environment or build up your PC image with your favorite apps. + +## Usage + +`winget import [-i] <import-file> [<options>]` + + + +## Arguments + +The following arguments are available. +| Argument | Description | +|-------------|-------------| +| **-i,--import-file** | JSON file describing the packages to install + +## Options + +The options allow you to customize the import experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **--ignore-unavailable** | Suppresses errors if the app requested is unavailable | +| **--ignore-versions** | Ignores versions specified in the JSON file and installs available | + +## JSON Schema +The driving force behind the **import** command is the JSON file. You can find the schema for the JSON file [here](https://aka.ms/winget-packages.schema.1.0.json). + +The JSON file includes the following hierarchy: +| Entry | Description | +|-------------|-------------| +| **Sources** | The repo that the the application is installed from. | +| **Packages** | The collection of packages to install. | +| **Id** | The Windows Package Manager id used to identify the package. | +| **Version** | [optional] The specific version of the package to install. | + +## Importing files + +When the Windows Package Manager imports the JSON file, it attempts to install the specified applications in a serial fashion. If the application is not available or the application is already installed, it will notify the user of that case. + + + +You will notice in the example above, the Microsoft.WindowsTerminal was already installed. Therefore the import command skipped passed the installation. diff --git a/doc/windows/package-manager/winget/index.md b/doc/windows/package-manager/winget/index.md @@ -54,13 +54,19 @@ The current preview of the **winget** tool supports the following commands. | Command | Description | |---------|-------------| +| [export](export.md) | Exports a list of the installed packages. | +| [features](features.md) | Shows the status of experimental features. | | [hash](hash.md) | Generates the SHA256 hash for the installer. | -| [help](help.md) | Displays help for the **winget** tool commands. | +| [import](import.md) | Installs all the packages in a file. | | [install](install.md) | Installs the specified application. | +| [list](list.md) | Display installed packages. | | [search](search.md) | Searches for an application. | +| [settings](settings.md) | Open settings. | | [show](show.md) | Displays details for the specified application. | | [source](source.md) | Adds, removes, and updates the Windows Package Manager repositories accessed by the **winget** tool. | | [validate](validate.md) | Validates a manifest file for submission to the Windows Package Manager repository. | +| [uninstall](uninstall.md) | Uninstalls the given package. | +| [upgrade](upgrade.md) | Upgrades the given package. | ### Options diff --git a/doc/windows/package-manager/winget/list.md b/doc/windows/package-manager/winget/list.md @@ -0,0 +1,83 @@ +--- +title: features Command +description: Displays the list of listed apps and if an update is available. +ms.date: 05/5/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# list command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **list** command of the [winget](index.md) tool displays a list of the applications currently installed on your computer. The list command will show apps that were installed through the Windows Package Manager as well as apps that were installed by other means. + +In addition, the **list** command will also display if an update is available for an app, and you can use the [**upgrade**](.\upgrade.md) command to update the app. + +The **list** command also supports filters which can be used to limit your list query. + +## Usage + +`winget list [[-q] \<query>] [\<options>]` + + + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Get additional help on this command. | + +## Options + +The options allow you to customize the list experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **--id** | Limits the list to the ID of the application. | +| **--name** | Limits the list to the name of the application. | +| **--moniker** | Limits the list to the moniker listed for the application. | +| **-s, --source** | Restricts the list to the source name provided. Must be followed by the source name. | +| **--tag** | Filters results by tags. | +| **--command** | Filters results by command specified by the application. | +| **-n, --count** | Limits the number of apps displayed in one query. | +| **-l, --location** | Location to list to (if supported). | +| **-e, --exact** | Uses the exact string in the list query, including checking for case-sensitivity. It will not use the default behavior of a substring. | + +### Example queries + +The following example lists a specific version of an application. + +```CMD +winget list --name powertoys + +``` + +The following example lists all application by ID from a specific source. + +```CMD +winget list --id Microsoft.PowerToys --source winget +``` + +The following example limits the output of list to 12 apps. + +```CMD +winget list -n 12 +``` + + + +## List with Update + +As stated above, the **list** command allows you to see what apps you have installed that have updates available. + +In the image below, you will notice the preview version of Terminal has an update available. + + + +The **list** command will show not only the update version available, but the source that the update is available from. + +* [Use the winget tool to list and manage applications](index.md) diff --git a/doc/windows/package-manager/winget/settings.md b/doc/windows/package-manager/winget/settings.md @@ -0,0 +1,139 @@ +--- +title: winget settings command +description: Provides customizations for the Windows Package Manager. +ms.date: 05/05/2021 +ms.topic: article +ms.localizationpriority: medium +--- + +# help command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **settings** command of the [winget](index.md) tool allows you to customize your Windows Package Manager client experience. You can change defaults and try out experimental features that are enabled in your client. +The **settings** command will launch your default MD editor. Windows by default will launch Notepad as an option. We recommend using a tool like [Visual Studio code](https://code.visualstudio.com/). + +>[!NOTE] +>You can easily install Visual Studio Code, by typing `winget install Microsoft.VisualStudioCode` + +## Usage + +Launch your favorite JSON editing tool: `winget settings` + + + +When you launch the settings for the first time, there will be no settings specified. At the top of the JSON we provide a [link](https://aka.ms/winget-settings) where you can discover the latest experimental features and settings. + +We have also defined a schema for the settings file. This allows you to use TAB to discover settings and syntax. + +## Updating Settings + +The following settings are available for the 1.0 release of the Windows Package Manager. + +### Source + +The `source` settings involve configuration to the WinGet source. + +```json + "source": { + "autoUpdateIntervalInMinutes": 3 + }, +``` + +#### autoUpdateIntervalInMinutes + +A positive integer represents the update interval in minutes. The check for updates only happens when a source is used. A zero will disable the check for updates to a source. Any other values are invalid. + +- Disable: 0 +- Default: 5 + +To manually update the source use `winget source update` + +### Visual + +The `visual` settings involve visual elements that are displayed by WinGet + +```json + "visual": { + "progressBar": "accent" + }, +``` + +#### progressBar + +Color of the progress bar that WinGet displays when not specified by arguments. + +- accent (default) +- retro +- rainbow + +### Install Behavior + +The `installBehavior` settings affect the default behavior of installing and upgrading (where applicable) packages. + +#### Preferences and Requirements + +Some of the settings are duplicated under `preferences` and `requirements`. `preferences` affect how the various available options are sorted when choosing the one to act on. For instance, the default scope of package installs is for the current user, but if that is not an option then a machine level installer will be chosen. `requirements` filter the options, potentially resulting in an empty list and a failure to install. In the previous example, a user scope requirement would result in no applicable installers and an error. + +Any arguments passed on the command line will effectively override the matching `requirement` setting for the duration of that command. + +#### Scope + +The `scope` behavior affects the choice between installing a package for the current user or for the entire machine. The matching parameter is `--scope`, and uses the same values (`user` or `machine`). + +```json + "installBehavior": { + "preferences": { + "scope": "user" + } + }, +``` + +#### Locale + +The `locale` behavior affects the choice of installer based on installer locale. The matching parameter is `--locale`, and uses bcp47 language tag. + +```json + "installBehavior": { + "preferences": { + "locale": [ "en-US", "fr-FR" ] + } + }, +``` + +### Telemetry + +The `telemetry` settings control whether winget writes ETW events that may be sent to Microsoft on a default installation of Windows. + +See [details on telemetry](https://github.com/microsoft/winget-cli/blob/master/README.md#datatelemetry), and our [primary privacy statement](https://github.com/microsoft/winget-cli/blob/master/privacy.md). + +#### disable + +``` + "telemetry": { + "disable": true + }, +``` + +If set to true, the `telemetry.disable` setting will prevent any event from being written by the program. + +### Network + +The `network` settings influence how winget uses the network to retrieve packages and metadata. + +#### Downloader + +The `downloader` setting controls which code is used when downloading packages. The default is `default`, which may be any of the options based on our determination. +`wininet` uses the [WinINet](https://docs.microsoft.com/en-us/windows/win32/wininet/about-wininet) APIs, while `do` uses the +[Delivery Optimization](https://support.microsoft.com/en-us/windows/delivery-optimization-in-windows-10-0656e53c-15f2-90de-a87a-a2172c94cf6d) service. + +```json + "network": { + "downloader": "do" + } +``` + +## Enabling Experimental features + +To discover which experimental features are available, go to [https://aka.ms/winget-settings](https://aka.ms/winget-settings) where you can see the experimental features available to you. + diff --git a/doc/windows/package-manager/winget/uninstall.md b/doc/windows/package-manager/winget/uninstall.md @@ -0,0 +1,80 @@ +--- +title: uninstall Command +description: uninstalls the specified application. +ms.date: 05/05/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# uninstall command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **uninstall** command of the [winget](index.md) tool uninstalls the specified application. + +The **uninstall** command requires that you specify the exact string to uninstall. If there is any ambiguity, you will be prompted to further filter the **uninstall** command to an exact application. + +## Usage + +`winget uninstall [[-q] \<query>] [\<options>]` + + + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Get additional help on this command. | + +## Options + +The options allow you to customize the uninstall experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **-m, --manifest** | Must be followed by the path to the manifest (YAML) file. You can use the manifest to run the uninstall experience from a [local YAML file](#local-uninstall). | +| **--id** | Limits the uninstall to the ID of the application. | +| **--name** | Limits the search to the name of the application. | +| **--moniker** | Limits the search to the moniker listed for the application. | +| **-v, --version** | Enables you to specify an exact version to uninstall. If not specified, latest will uninstall the highest versioned application. | +| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. | +| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. | +| **-i, --interactive** | Runs the uninstaller in interactive mode. The default experience shows uninstaller progress. | +| **-h, --silent** | Runs the uninstaller in silent mode. This suppresses all UI. The default experience shows uninstaller progress. | +| **-o, --log** | Directs the logging to a log file. You must provide a path to a file that you have the write rights to. | + +Once you have successfully identified the application intended to uninstall, winget will execute the uninstall command. In the example below, the **name** 'orca' and the **id** was passed in. + + + + +### Example queries + +The following example uninstalls a specific version of an application. + +```CMD +winget uninstall --name powertoys --version 0.15.2 +``` + +The following example uninstalls an application using its ID. + +```CMD +winget uninstall --id "{24559D0F-481C-F3BE-8DD0-D908923A38F8}" +``` + +## Multiple selections + +If the query provided to **winget** does not result in a single application to uninstall, then **winget** will display multiple results. You can then use additional filters to refine the search for a correct application. + + + +## Uninstalling apps not installed with Windows Package Manager +As mentioned in [**list**](.\list.md), the **winget list** command will display more than just apps installed with the **winget**. Therefore you can use these commands to quickly and easily remove apps from your PC. + +In this example, **list** was used to find the application, and then the **id** was passed in as part of uninstall. + + + diff --git a/doc/windows/package-manager/winget/upgrade.md b/doc/windows/package-manager/winget/upgrade.md @@ -0,0 +1,85 @@ +--- +title: upgrade Command +description: upgrades the specified application. +ms.date: 05/05/2021 +ms.topic: overview +ms.localizationpriority: medium +--- + +# upgrade command (winget) + +[!INCLUDE [preview-note](../../includes/package-manager-preview.md)] + +The **upgrade** command of the [winget](index.md) tool upgrades the specified application. Use the [**list**](.\list.md) command to identify the application you want to upgrade. + +The **upgrade** command requires that you specify the exact string to upgrade. If there is any ambiguity, you will be prompted to further filter the **upgrade** command to an exact application. + +## Usage + +`winget upgrade [[-q] \<query>] [\<options>]` + + + +## Arguments + +The following arguments are available. + +| Argument | Description | +|-------------|-------------| +| **-q,--query** | The query used to search for an app. | +| **-?, --help** | Get additional help on this command. | + +## Options + +The options allow you to customize the upgrade experience to meet your needs. + +| Option | Description | +|-------------|-------------| +| **-m, --manifest** | Must be followed by the path to the manifest (YAML) file. You can use the manifest to run the upgrade experience from a [local YAML file](#local-upgrade). | +| **--id** | Limits the upgrade to the ID of the application. | +| **--name** | Limits the search to the name of the application. | +| **--moniker** | Limits the search to the moniker listed for the application. | +| **-v, --version** | Enables you to specify an exact version to upgrade. If not specified, latest will upgrade the highest versioned application. | +| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. | +| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. | +| **-i, --interactive** | Runs the installer in interactive mode. The default experience shows installer progress. | +| **-h, --silent** | Runs the installer in silent mode. This suppresses all UI. The default experience shows installer progress. | +| **-o, --log** | Directs the logging to a log file. You must provide a path to a file that you have the write rights to. | +| **--override** | A string that will be passed directly to the installer. | +| **-l, --location** | Location to upgrade to (if supported). | +| **--force** | When a hash mismatch is discovered will ignore the error and attempt to install the package. | +| **--all** | Updates all available packages to the latest application. | +### Example queries + +The following example upgrades a specific version of an application. + +```CMD +winget upgrade powertoys --version 0.15.2 +``` + +The following example upgrades an application from its ID. + +```CMD +winget upgrade --id Microsoft.PowerToys +``` + +The following example shows upgrading all apps + +```CMD +winget upgrade --all +``` + +## Using **list** and **upgrade** + +It is common to use the [**list**](.\list.md) command to identify apps in need of an update, and then to use **upgrade** to install the latest. + +In the example below you will see [**list**](.\list.md) identifies that an update is available for Microsoft.WindowsTerminalPreview, and then the user uses **upgrade** to update the application. + + + +## **upgrade** --all + +**upgrade --all** will identify all the applications with upgrades available. When you run **winget upgrade --all** the Windows Package Manager will look for all applications that have updates available and attempt to install the. + +>[!NOTE] +Some applications do not provide a version. They are always latest. Because the Windows Package Manager cannot identify if their is a newer version of the app, an upgrade will not be possible.
