Skip to content

Commit b6ccb88

Browse files
ryfu-msftRyan Fumattwojo
authored
Add page for WinGet pinning (#3654)
* add page for winget pinning * add pin command to toc.yml * remove single quotes * fix title * fix title #2 * Formatting updates --------- Co-authored-by: Ryan Fu <[email protected]> Co-authored-by: Matt Wojciakowski <[email protected]>
1 parent 1a75e54 commit b6ccb88

File tree

2 files changed

+233
-0
lines changed

2 files changed

+233
-0
lines changed

‎hub/dev-environment/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ items:
3939
href: ../package-manager/winget/install.md
4040
- name: list command
4141
href: ../package-manager/winget/list.md
42+
- name: pin command
43+
href: ../package-manager/winget/pinning.md
4244
- name: search command
4345
href: ../package-manager/winget/search.md
4446
- name: settings command

‎hub/package-manager/winget/pinning.md

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
title: pin Command
3+
description: Pin a package to a specific version or within a specific version range using WinGet, the Windows Package Manager client.
4+
ms.date: 07/05/2023
5+
ms.topic: reference
6+
---
7+
8+
# pin command (winget)
9+
10+
The [winget](index.md) **pin** command allows you to limit the Windows Package Manager from upgrading a package to specific ranges of versions, or it can prevent it from upgrading a package altogether. A pinned package may still upgrade on its own and be upgraded from outside the Windows Package Manager.
11+
12+
## Pin Types
13+
14+
WinGet supports three types of package pins:
15+
16+
- **Pinning**: The package is excluded from `winget upgrade --all` but allows `winget upgrade <package>`. You can use the `--include-pinned` argument to let `winget upgrade --all` include pinned packages.
17+
18+
- **Blocking**: The package is blocked from `winget upgrade --all` or `winget upgrade <package>`, you will have to unpin the package to let WinGet perform an upgrade. The `--force` option can be used to override the pin's behavior.
19+
20+
- **Gating**: The package is pinned to a specific version or version range. You can specify an exact version you want a package to be pinned to or you can utilize the wildcard character `*` as the last version part to specify a version range. For example, if a package is pinned to version `1.2.*`, any version between `1.2.0` to `1.2.x` is considered valid. The `--force` option can be used to override the pin's behavior.
21+
22+
## Usage
23+
24+
```cmd
25+
winget pin <subcommand> <options>
26+
```
27+
28+
## Arguments
29+
30+
The following arguments are available.
31+
32+
| Argument | Description |
33+
|--------------|-------------|
34+
| **-?, --help** | Gets additional help on this command. |
35+
36+
## Subcommands
37+
38+
The **pin** command supports the following subcommands.
39+
40+
| Subcommand | Description |
41+
|--------------|-------------|
42+
| **add** | Add a new pin. |
43+
| **remove** | Remove a package pin. |
44+
| **list** | List current pins. |
45+
| **reset** | Reset pins |
46+
47+
## add
48+
49+
The **add** subcommand adds a new pin. This subcommand requires that you specify the exact package to pin. If there is any ambiguity, you will be prompted to further filter the **add** subcommand to an exact application.
50+
51+
Usage:
52+
53+
```cmd
54+
winget pin add [[-q] <query>] [<options>]
55+
```
56+
57+
### Arguments
58+
59+
| Argument | Description |
60+
|-------------|-------------|
61+
| **-q,--query** | The query used to search for an app. |
62+
| **-?, --help** | Get additional help on this command. |
63+
64+
### Options
65+
66+
The options allow you to customize adding pins to meet your needs.
67+
68+
| Option | Description |
69+
|-------------|-------------|
70+
| **--id** | Limits the search to the ID of the application. |
71+
| **--name** | Limits the search to the name of the application. |
72+
| **--moniker** | Limits the search to the moniker listed for the application. |
73+
| **--tag** | Limits the search to the tag listed for the application. |
74+
| **--cmd, --command** | Limits the search to the command of the application. |
75+
| **-v, --version** | Enables you to specify an exact version to pin. The wildcard * can be used as the last version part. Changes pin behavior to be [`gating`](#pin-types). |
76+
| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. |
77+
| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. |
78+
| **--force** | Direct run the command and continue with non security related issues. |
79+
| **--blocking** | Block from upgrading until the pin is removed, preventing override arguments. Changes pin behavior to be [`blocking`](#pin-types). |
80+
| **--installed** | Pin a specific installed version |
81+
| **--accept-source-agreements** | Used to accept the source license agreement, and avoid the prompt. |
82+
| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
83+
| **--wait** | Prompts the user to press any key before exiting |
84+
| **--logs, --open-log** | Open the default logs location. |
85+
| **--verbose-logs** | Used to override the logging setting and create a verbose log. |
86+
| **--disable-interactivity** | Disable interactive prompts. |
87+
88+
### Examples
89+
90+
The following example adds a pin for an application. Adding this pin will prevent this package from being upgraded when calling `winget upgrade --all`. Use the `--include-pinned` argument with `winget upgrade --all` to include any pinned packages.
91+
92+
```cmd
93+
winget pin add powertoys
94+
```
95+
96+
The following example adds a blocking pin for an application using its ID. Adding a blocking pin will prevent this package from being upgraded when calling `winget upgrade --all` or `winget upgrade <package>`. You will need to unblock the package to let WinGet perform an upgrade.
97+
98+
```cmd
99+
winget pin add --id Microsoft.PowerToys --blocking
100+
```
101+
102+
The following example adds a gating pin for an application using its ID. Adding a gating pin will prevent upgrades that upgrade the package version outside of a specific version or the gated wildcard range.
103+
104+
```cmd
105+
winget pin add --id Microsoft.PowerToys --version 0.70.*
106+
```
107+
108+
## remove
109+
110+
The **remove** subcommand removes a pin. This subcommand requires that you specify the exact package pin to remove. If there is any ambiguity, you will be prompted to further filter the **remove** subcommand to an exact application.
111+
112+
Usage:
113+
114+
```cmd
115+
winget pin remove [[-q] <query>] [<options>]
116+
```
117+
118+
### Arguments
119+
120+
| Argument | Description |
121+
|-------------|-------------|
122+
| **-q,--query** | The query used to search for an app. |
123+
| **-?, --help** | Get additional help on this command. |
124+
125+
### Options
126+
127+
The options allow you to customize removing pins to meet your needs.
128+
129+
| Option | Description |
130+
|-------------|-------------|
131+
| **--id** | Limits the search to the ID of the application. |
132+
| **--name** | Limits the search to the name of the application. |
133+
| **--moniker** | Limits the search to the moniker listed for the application. |
134+
| **--tag** | Limits the search to the tag listed for the application. |
135+
| **--cmd, --command** | Limits the search to the command of the application. |
136+
| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. |
137+
| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. |
138+
| **--installed** | Pin a specific installed version |
139+
| **--accept-source-agreements** | Used to accept the source license agreement, and avoid the prompt. |
140+
| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
141+
| **--wait** | Prompts the user to press any key before exiting |
142+
| **--logs, --open-log** | Open the default logs location. |
143+
| **--verbose-logs** | Used to override the logging setting and create a verbose log. |
144+
| **--disable-interactivity** | Disable interactive prompts. |
145+
146+
### Examples
147+
148+
The following example removes a pin for an application.
149+
150+
```cmd
151+
winget pin remove powertoys
152+
```
153+
154+
The following example removes a pin for an application using its ID.
155+
156+
```cmd
157+
winget pin remove --id Microsoft.PowerToys
158+
```
159+
160+
## list
161+
162+
The **list** subcommand lists all current pins.
163+
164+
Usage:
165+
166+
```cmd
167+
winget pin list [[-q] <query>] [<options>]
168+
```
169+
170+
### Arguments
171+
172+
| Argument | Description |
173+
|-------------|-------------|
174+
| **-q,--query** | The query used to search for an app. |
175+
| **-?, --help** | Get additional help on this command. |
176+
177+
### Options
178+
179+
The options allow you to customize listing pins to meet your needs.
180+
181+
| Option | Description |
182+
|-------------|-------------|
183+
| **--id** | Limits the search to the ID of the application. |
184+
| **--name** | Limits the search to the name of the application. |
185+
| **--moniker** | Limits the search to the moniker listed for the application. |
186+
| **--tag** | Limits the search to the tag listed for the application. |
187+
| **--cmd, --command** | Limits the search to the command of the application. |
188+
| **-s, --source** | Restricts the search to the source name provided. Must be followed by the source name. |
189+
| **-e, --exact** | Uses the exact string in the query, including checking for case-sensitivity. It will not use the default behavior of a substring. |
190+
| **--accept-source-agreements** | Used to accept the source license agreement, and avoid the prompt. |
191+
| **--header** | Optional Windows-Package-Manager REST source HTTP header. |
192+
| **--wait** | Prompts the user to press any key before exiting |
193+
| **--logs, --open-log** | Open the default logs location. |
194+
| **--verbose-logs** | Used to override the logging setting and create a verbose log. |
195+
| **--disable-interactivity** | Disable interactive prompts. |
196+
197+
### Examples
198+
199+
The following example lists all current pins.
200+
201+
```cmd
202+
winget pin list
203+
```
204+
205+
The following example lists a specific package pin.
206+
207+
```cmd
208+
winget pin list --id Microsoft.PowerToys
209+
```
210+
211+
## reset
212+
213+
The reset subcommand resets all pins.
214+
215+
Using this subcommand without the `--force` argument will show the pins that would be removed.
216+
217+
To reset all pins, include the `--force` argument.
218+
219+
Usage:
220+
221+
The following example shows all pins that would be reset.
222+
223+
```cmd
224+
winget pin reset
225+
```
226+
227+
The following example resets all existing pins.
228+
229+
```cmd
230+
winget pin reset --force
231+
```

0 commit comments

Comments
 (0)