Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for winget commands #3909

Merged
merged 12 commits into from
Nov 20, 2023
6 changes: 6 additions & 0 deletions doc/windows/package-manager/winget/export.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,12 @@ The options allow you to customize the export experience to meet your needs.
|--------|-------------|
| **-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. |
| **--accept-source-agreements** | Accept all source agreements during source operations |
| **-?, --help** | Shows help about the selected command |
| **--wait** | Prompts the user to press any key before exiting |
| **--logs, --open-logs** | Open the default logs location |
| **--verbose, --verbose-logs** | Enables verbose logging for winget |
| **--disable-interactivity** | Disable interactive prompts |

## 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).
Expand Down
16 changes: 14 additions & 2 deletions doc/windows/package-manager/winget/hash.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,21 @@ The following arguments are available:

| Argument | Description |
|--------------|-------------|
| **-f,--file** | The path to the file to be hashed. |
| **-m,--msix** | Specifies that the hash command will also create the SHA-256 SignatureSha256 for use with MSIX installers. |
| **-f, --file** | The path to the file to be hashed. |

## Options

The following options are available:

| Option | Description |
|--------|-------------|
| **-m, --msix** | Specifies that the hash command will also create the SHA-256 SignatureSha256 for use with MSIX installers. |
| **-?, --help** | Gets additional help on this command. |
| **--wait** | Prompts the user to press any key before exiting |
| **--logs, --open-logs** | Open the default logs location |
| **--verbose, --verbose-logs** | Enables verbose logging for winget |
| **--disable-interactivity** | Disable interactive prompts |


## Related topics

Expand Down
10 changes: 9 additions & 1 deletion doc/windows/package-manager/winget/import.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The **import** command is often used to share your developer environment or buil
The following arguments are available.
| Argument | Description |
|-------------|-------------|
| **-i,--import-file** | JSON file describing the packages to install
| **-i, --import-file** | JSON file describing the packages to install

## Options

Expand All @@ -33,6 +33,14 @@ The options allow you to customize the import experience to meet your needs.
|-------------|-------------|
| **--ignore-unavailable** | Suppresses errors if the app requested is unavailable |
| **--ignore-versions** | Ignores versions specified in the JSON file and installs the latest available version |
| **--no-upgrade** | Skips upgrade if an installed version already exists |
| **--accept-package-agreements** | Accept all license agreements for packages |
| **--accept-source-agreements** | Accept all source agreements during source operations |
| **-?, --help** | Shows help about the selected command |
| **--wait** | Prompts the user to press any key before exiting |
| **--logs, --open-logs** | Open the default logs location |
| **--verbose, --verbose-logs** | Enables verbose logging for winget |
| **--disable-interactivity** | Disable interactive prompts |

## 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).
Expand Down
7 changes: 6 additions & 1 deletion doc/windows/package-manager/winget/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,6 @@ One of the most common usage scenarios is to search for and install a favorite t
### Commands

The current preview of the **winget** tool supports the following commands.

| Command | Description |
|---------|-------------|
| [install](install.md) | Installs the specified application. |
Expand All @@ -61,6 +60,9 @@ The current preview of the **winget** tool supports the following commands.
| [features](features.md) | Shows the status of experimental features. |
| [export](export.md) | Exports a list of the installed packages. |
| [import](import.md) | Installs all the packages in a file. |
| pin | Manage package pins. |
| configure | Configures the system into a desired state. |
| download | Downloads the installer from a given package. |

### Options

Expand All @@ -72,6 +74,9 @@ The current version of the **winget** tool supports the following options.
| **--info** | Provides you with all detailed information on winget, including the links to the license, privacy statement, and configured group policies. |
| **-?, --help** | Shows additional help for winget. |
| **--wait** | Waits for user input upon command completion. |
| **--logs,--open-logs** | Open the default logs location |
| **--verbose,--verbose-logs** | Enables verbose logging for winget |
| **--disable-interactivity** | Disable interactive prompts |

## Supported installer formats

Expand Down
26 changes: 24 additions & 2 deletions doc/windows/package-manager/winget/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ The **install** command requires that you specify the exact string to install. I

`winget install [[-q] <query>] [<options>]`

The following command aliases are available: \
`add`

![search command](images/install.png)

## Arguments
Expand All @@ -24,8 +27,7 @@ The following arguments are available.

| Argument | Description |
|-------------|-------------|
| **-q,--query** | The query used to search for an app. |
| **-?, --help** | Get additional help on this command. |
| **-q, --query** | The query used to search for an app. |

## Options

Expand All @@ -47,6 +49,26 @@ The options allow you to customize the install experience to meet your needs.
| **--override** | A string that will be passed directly to the installer. |
| **-l, --location** | Location to install to (if supported). |
| **--force** | Override the installer hash check. |
| **-a, --architecture** | Select the architecture |
| **--installer-type** | Select the installer type |
| **--locale** | Locale to use (BCP47 format) |
| **--custom** | Arguments to be passed on to the installer in addition to the defaults |
| **--ignore-security-hash** | Ignore the installer hash check failure |
| **--skip-dependencies** | Skip processing package dependencies and Windows features |
| **--ignore-local-archive-malware-scan** | Ignore the malware scan performed as part of installing an archive-type package from a local manifest |
| **--dependency-source** | Find package dependencies using the specified source |
| **--accept-package-agreements** | Accept all license agreements for packages |
| **--no-upgrade** | Skip upgrade if an installed version already exists |
| **--header** | Optional Windows-Package-Manager REST source HTTP header |
| **--accept-source-agreements** | Accept all source agreements during source operations |
| **-r, --rename** | The value to rename the executable file (portable) |
| **--uninstall-previous** | Uninstall the previous version of the package during the upgrade |
| **--ignore-interactivity** | Disable interactive prompts |
| **-?, --help** | Get additional help on this command. |
| **--wait** | Prompts the user to press any key before exiting |
| **--logs, --open-logs** | Open the default logs location |
| **--verbose, --verbose-logs** | Enables verbose logging for winget |
| **--disable-interactivity** | Disable interactive prompts |

### Example queries

Expand Down
28 changes: 20 additions & 8 deletions doc/windows/package-manager/winget/list.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@ The **list** command also supports filters which can be used to limit your list

`winget list [[-q] <query>] [<options>]`

The following command aliases are available: \
`ls`

![list help command](images/list.png)

## Arguments
Expand All @@ -27,22 +30,31 @@ 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. |
| 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. |
| **-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. |
| **-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. |
| **--scope** | Select installed package scope filter (user or machine). |
| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
| **--accept-source-agreements** | Accept all source agreements during source operations. |
| **--upgrade-available** | Lists only packages which have an upgrade available. |
| **-u,--unknown,--include-unknown** | List packages even if their current version cannot be determined. Can only be used with the --upgrade-available argument. |
| **--pinned,--include-pinned** | List packages even if they have a pin that prevents upgrade. Can only be used with the --upgrade-available argument. |
| **-?,--help** | Get additional help on this command. |
| **--wait** | Prompts the user to press any key before exiting. |
| **--logs,--open-logs** | Open the default logs location. |
| **--verbose,--verbose-logs** | Enables verbose logging for winget. |
| **--disable-interactivity** | Disable interactive prompts. |

### Example queries

Expand Down
19 changes: 16 additions & 3 deletions doc/windows/package-manager/winget/search.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ The **search** command can show all applications available, or it can be filtere

`winget search [[-q] <query>] [<options>]`

The following command aliases are available: \
`find`

![Screenshot of the Windows Power Shell window displaying the results of the winget search.](images/search.png)

## Arguments
Expand All @@ -24,8 +27,7 @@ The following arguments are available.

| Argument | Description |
--------------|-------------|
| **-q,--query** | The query used to search for an app. |
| **-?, --help** | Gets additional help on this command. |
| **-q, --query** | The query used to search for an app. |

## Show all

Expand All @@ -41,7 +43,18 @@ Search strings can be filtered with the following options.
| **--name** | Limits the search to the name of the application. |
| **--moniker** | Limits the search to the moniker specified. |
| **--tag** | Limits the search to the tags listed for the application. |
| **--command** | Limits the search to the commands listed for the application. |
| **--cmd, --command** | Limits the search to the commands listed for the application. |
| **-s, --source** | Find package using the specified source. |
| **-n, --count** | Show no more than specified number of results (between 1 and 1000). |
| **-e, --exact** | Find package using exact match. |
| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
| **--accept-source-agreements** | Accept all source agreements during source operations. |
| **--versions** | Show available versions of the package. |
| **-?, --help** | Gets additional help on this command. |
| **--wait** | Prompts the user to press any key before exiting. |
| **--logs, --open-logs** | Open the default logs location. |
| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
| **--disable-interactivity** | Disable interactive prompts. |

The string will be treated as a substring. The search by default is also case insensitive. For example, `winget search micro` could return the following:

Expand Down
17 changes: 15 additions & 2 deletions doc/windows/package-manager/winget/show.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ The **show** command only shows metadata that was submitted with the application

`winget show [[-q] <query>] [<options>]`

The following command aliases are available: \
`view`

![show command](images/show.png)

## Arguments
Expand All @@ -24,8 +27,7 @@ The following arguments are available.

| Argument | Description |
|--------------|-------------|
| **-q,--query** | The query used to search for an application. |
| **-?, --help** | Gets additional help on this command. |
| **-q, --query** | The query used to search for an application. |

## Options

Expand All @@ -41,6 +43,17 @@ The following options are available.
| **-s,--source** | Find the application using the specified [source](source.md). |
| **-e,--exact** | Find the application using exact match. |
| **--versions** | Show available versions of the application. |
| **--scope** | Select install scope (user or machine). |
| **-a, --architecture** | Select the architecture. |
| **--installer-type** | Select the installer type. |
| **--locale** | Locale to use (BCP47 format). |
| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
| **--accept-source-agreements** | Accept all source agreements during source operations. |
| **-?, --help** | Gets additional help on this command. |
| **--wait** | Prompts the user to press any key before exiting. |
| **--logs, --open-logs** | Open the default logs location. |
| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
| **--disable-interactivity** | Disable interactive prompts. |

## Multiple selections

Expand Down
14 changes: 10 additions & 4 deletions doc/windows/package-manager/winget/source.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ A source provides the data for you to discover and install applications. Only ad

## Usage

`winget source <sub-command> <options>`
`winget source [<command>] [<options>]`

![Source image](images/source.png)

Expand All @@ -41,16 +41,22 @@ Source supports the following sub-commands for manipulating the sources.
| **reset** | Resets **winget** back to the initial configuration. |
| **export** | Export current sources |

For more details on a specific command, pass it the help argument. [-?]

## Options

The **source** command supports the following options.

| Option | Description |
|--------------|-------------|
| **-n,--name** | The name to identify the source by. |
| **-a,--arg** | The URL or UNC of the source. |
| **-t,--type** | The type of source. |
| **-n, --name** | The name to identify the source by. |
| **-a, --arg** | The URL or UNC of the source. |
| **-t, --type** | The type of source. |
| **-?, --help** | Gets additional help on this command. |
| **--wait** | Prompts the user to press any key before exiting. |
| **--logs, --open-logs** | Open the default logs location. |
| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
| **--disable-interactivity** | Disable interactive prompts. |

## add

Expand Down
39 changes: 27 additions & 12 deletions doc/windows/package-manager/winget/uninstall.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,11 @@ The **uninstall** command requires that you specify the exact string to uninstal

## Usage

`winget uninstall [[-q] <query>] [<options>]`
`winget uninstall [[-q] <query>...] [<options>]`

The following command aliases are available: \
`remove` \
`rm`

![uninstall command](images/uninstall.png)

Expand All @@ -25,24 +29,35 @@ 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. |
| **--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, the 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. |
| **--product-code** | Filters using the product code. |
| **--scope** | Select installed package scope filter (user or machine). |
| **--force** | Directly run the command and continue with non-security-related issues. |
| **--purge** | Deletes all files and directories in the package directory (portable). |
| **--preserve** | Retains all files and directories created by the package (portable). |
| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
| **--accept-source-agreements** | Accept all source agreements during source operations. |
| **-?, --help** | Get additional help on this command. |
| **--wait** | Prompts the user to press any key before exiting. |
| **--logs, --open-logs** | Open the default logs location. |
| **--verbose, --verbose-logs** | Enables verbose logging for winget. |
| **--disable-interactivity** | Disable interactive prompts. |

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.

Expand Down
5 changes: 4 additions & 1 deletion doc/windows/package-manager/winget/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@ The **upgrade** command requires that you specify the exact string to upgrade. I

## Usage

`winget upgrade [[-q] <query>] [<options>]`
`winget upgrade [[-q] <query>...] [<options>]`

The following command aliases are available: \
`update`

![upgrade command](images/upgrade.png)

Expand Down