Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 326d914

Browse files
OctomergerOctomerger
authored
Merge pull request #23495 from github/repo-sync
repo sync
2 parents 93bdf6b + a04d978 commit 326d914

2 files changed

Lines changed: 190 additions & 10 deletions

File tree

‎assets/images/help/projects-v2/filter-example.png‎

13.2 KB
Loading

‎content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md‎

Lines changed: 190 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: 'Filtering {% data variables.projects.projects_v2 %}'
3-
intro: Use filters to choose which items appear in your project's views.
3+
intro: "Use filters to choose which items appear in your project's views."
44
miniTocMaxHeadingLevel: 3
55
versions:
66
feature: projects-v2
@@ -12,22 +12,202 @@ topics:
1212
allowTitleToDifferFromFilename: true
1313
---
1414

15-
You can customize views using filters for item metadata, such as assignees and the labels applied to issues, and by the fields in your project. You can combine filters and save them as views. For more information, see "[Customizing your project views](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-a-view)."
15+
You can customize which items appear in your views using filters for item metadata, such as assignees and the labels applied to issues, and by the fields in your project. You can combine filters and save them as views. For more information, see "[Managing your views](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/managing-your-views)."
1616

17-
To filter a project, click {% octicon "filter" aria-label="The Filter icon" %} and start typing the fields and values you would like to filter for. As you type, possible values will appear. You can also open the project command palette, by pressing {% data variables.projects.command-palette-shortcut %}, and type "Filter by" to choose from the available filters.
17+
To filter a view, click {% octicon "filter" aria-label="The Filter icon" %} and start typing the fields and values you would like to filter for. As you type, possible values will appear. You can also open the project command palette, by pressing {% data variables.projects.command-palette-shortcut %}, and type "Filter by" to choose from the available filters.
1818

19-
Using multiple filters will act as a logical AND filter. For example, `label:bug status:"In progress"` will return items with the `bug` label with the "In progress" status. {% data variables.product.prodname_projects_v2 %} does not currently support logical OR filters across multiple fields.
19+
![Screenshot showing the location of the filter icon](/assets/images/help/projects-v2/filter-example.png)
20+
21+
In board layout, you can click on item data to filter for items with that value. For example, click on an assignee to show only items for that assignee. To remove the filter, click the item data again.
22+
23+
Using multiple filters will act as a logical AND filter. For example, `label:bug status:"In progress"` will return items with the `bug` label and the "In progress" status. You can also provide multiple values for the same field to act as a logical OR filter. For example, `label:bug,support` will return items with either the `bug` or `support` labels. {% data variables.product.prodname_projects_v2 %} does not currently support logical OR filters across multiple fields.
2024

2125
The same filters are available for charts you create using insights for {% data variables.product.prodname_projects_v2 %}, allowing you to filter the data used to create your charts. For more information, see "[Using insights with projects](/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects)."
2226

23-
When you filter a view and then add an item, the filtered metadata will be applied to added item. For example, if you're filtering by `status:"In progress"` and you add an item, the new item will have its status set to "In progress."
27+
When you filter a view and then add an item, the filtered metadata will be applied to new item. For example, if you're filtering by `status:"In progress"` and you add an item, the new item will have its status set to "In progress."
2428

25-
## Filtering items
29+
You can use filters to produce views for very specific purposes. For example, you could use `assignee:@me status:todo last-updated:5days` to create a view of all work assigned to the current user, with the "todo" status, that hasn't been updated in the last five days. You could create a triage view by using a negative filter, such as `no:label no:assignee repo:octocat/game`, which would show items without a label and without an assignee that are located in the `octocat/game` repository.
2630

27-
Click {% octicon "filter" aria-label="the filter icon" %} at the top of the table to show the "Filter by keyword or by field" bar. Start typing the field name and value that you want to filter by. As you type, possible values will appear.
31+
### Filtering for fields
2832

29-
{% data reusables.projects.projects-filters %}
33+
| Qualifier | Example
34+
| ---------- | -------------
35+
| <code>assignee:<em>USERNAME</em></code> | **assignee:octocat** will show items assigned to @octocat.
36+
| <code>label:<em>LABEL</em></code> | **label:bug** will show items with the "bug" label applied.
37+
| <code>field:<em>VALUE</em></code> | **status:done** will show items with the "status" field set to "done."
38+
| <code>reviewers:<em>USERNAME</em> | **reviewers:octocat** will show items that have been reviewed by @octocat.
39+
| <code>milestone:&quot;<em>MILESTONE</em>&quot; | **milestone:"Beta release"** will show items assigned to the "Beta release" milestone.
3040

31-
Alternatively, open the project command palette by pressing {% data variables.projects.command-palette-shortcut %} and start typing "Filter by."
41+
### Combining filters
3242

33-
In board layout, you can click on item data to filter for items with that value. For example, click on an assignee to show only items for that assignee. To remove the filter, click the item data again.
43+
You can create filters for multiple fields. Your view will show items that match all filters.
44+
45+
| Qualifier | Example
46+
| ---------- | -------------
47+
|<code>assignee:<em>USERNAME</em> field:<em>VALUE</em></code> | **assignee:octocat priority:1** will show items assigned to @octocat that have a priority of **1**.
48+
49+
You can also filter for multiple values from the same field. If you separate the values with commas, your view will show items that match any of the provided values.
50+
51+
| Qualifier | Example
52+
| ---------- | -------------
53+
|<code>assignee:<em>USERNAME</em>,<em>USERNAME</em></code> | **assignee:octocat,stevecat** will show items assigned to either @octocat or @stevecat.
54+
55+
To filter for multiple values from the same field but show items that match all of the provided values, you can repeat the qualifier for each value.
56+
57+
| Qualifier | Example
58+
| ---------- | -------------
59+
|<code>assignee:<em>USERNAME</em> assignee:<em>USERNAME</em></code> | **assignee:octocat assignee:stevecat** will show items that are assigned to both @octocat and @stevecat.
60+
61+
You can also combine filters that match some and match all items.
62+
63+
| Qualifier | Example
64+
| ---------- | -------------
65+
|<code>field:<em>VALUE</em>,<em>VALUE</em> assignee:<em>USER</em> assignee:<em>USER</em> | **label:bug,onboarding assignee:octocat assignee:stevecat** will show items that have either the bug or onboarding labels but are assigned to both @octocat and @stevecat.
66+
67+
### Negating a filter
68+
69+
You can invert any filter, including combinations, by prefixing with a hyphen.
70+
71+
| Qualifier | Example
72+
| ---------- | -------------
73+
|<code>-assignee:<em>USERNAME</em></code> | **-assignee:octocat** will not show any items assigned to @octocat.
74+
|<code>-field:<em>VALUE</em></code> | **-status:done** will not show any items with a status of "done."
75+
|<code>-field:<em>VALUE,VALUE</em></code> | **-priority:1,2** will not show any items with a priority of either 1 or 2.
76+
77+
### Filtering for items that are missing a value
78+
79+
You can use `no:` to filter for items that are missing a value
80+
81+
| Qualifier | Example
82+
| ---------- | -------------
83+
|<code>no:assignee</code> | **no:assignee** will show any unassigned items.
84+
|<code>no:reviewers</code> | **no:reviewers** will show pull requests that do not have a reviewer.
85+
|<code>no:<em>FIELD</em> | **no:priority** will show items with an empty priority field.
86+
87+
You can also prefix a hyphen to negate this behavior and only return items that have a value.
88+
89+
| Qualifier | Example
90+
| ---------- | -------------
91+
|<code>-no:assignee</code> | **-no:assignee** will only show items that are assigned.
92+
|<code>-no:<em>FIELD</em></code> | **-no:priority** will only show items that have a value in the priority field.
93+
94+
### Filtering by item location
95+
96+
Use the `repo` qualifier to filter for items in a particular repository.
97+
98+
| Qualifier | Example
99+
| ---------- | -------------
100+
|<code>repo:<em>OWNER/REPO</em></code> | **repo:octocat/game** will items in the "octocat/game" repository.
101+
102+
### Filtering for item state or item type
103+
104+
You can use the `is` qualifier to filter for particular types of item or items in particular states.
105+
106+
| Qualifier | Example
107+
| ---------- | -------------
108+
|<code>is:<em>STATE</em></code> | **is:open** will show open issues and pull requests.
109+
| | **is:closed** will show closed issues and pull requests.
110+
| | **is:merged** will show any merged pull requests.
111+
|<code>is:<em>TYPE</em></code> | **is:issue** will show only issues.
112+
| | **is:pr** will show only pull requests.
113+
| | **is:draft** will show draft issues and draft pull requests.
114+
| | **is:issue is:open** will show open issues.
115+
116+
### Filtering by close reason
117+
118+
You can filter closed items by their close reason.
119+
120+
| Qualifier | Example
121+
| ---------- | -------------
122+
|<code>reason:<em>CLOSE REASON</em></code> | **reason:completed** will show items closed because they were completed.
123+
| | **reason:"not planned"** will show closed items with the "not planned" reason.
124+
| | **reason:reopened** will show items that have been reopened after previously being closed.
125+
126+
{% ifversion projects-v2-tasklists %}
127+
128+
### Filtering by the tracked-by field
129+
130+
You can filter for issues that being tracked by another issue in a Tasklist. For more information, see "[About Tasklists](/issues/tracking-your-work-with-issues/about-tasklists)."
131+
132+
| Qualifier | Example
133+
| ---------- | -------------
134+
| <code>tracked-by:"<em>OWNER</em>/<em>REPO</em>#<em>ISSUE NUMBER</em>"</code> | **tracked-by:"octocat/game#11"** will show any issue tracked by a Tasklist in issue #11 of the `octocat/game` repository.
135+
136+
{% endif %}
137+
138+
### Filtering for when an item was last updated
139+
140+
You can use the `{number}days` syntax to filter for when items were last updated.
141+
142+
| Qualifier | Example
143+
| ---------- | -------------
144+
| <code>last-updated:<em>NUMBER</em>days</code> | **last-updated:1day** will show items last updated one or more days ago.
145+
| | **last-updated:7days** will show items last updated seven or more days ago.
146+
| | **-last-updated:10days** will show items that have been updated in the last ten days.
147+
148+
### Filtering number, date, and iteration fields
149+
150+
You can use `>`, `>=`, `<`, and `<=` to compare number, date, and iteration fields. Dates should be provided in the `YYYY-MM-DD` format.
151+
152+
| Qualifier | Example
153+
| ---------- | -------------
154+
| <code>field:&gt;<em>VALUE</em></code> | **priority:&gt;1** will show items with a priority greater than 1.
155+
| <code>field:&gt;=<em>VALUE</em></code> | **date:&gt;=2022-06-01** will show items with a date of "2022-06-01" or later.
156+
| <code>field:&lt;<em>VALUE</em></code> | **iteration:<"Iteration 5"** will show items with an iteration before "Iteration 5."
157+
| <code>field:&gt;=<em>VALUE</em></code> | **points:&lt;=10** will show items with 10 or less points.
158+
159+
You can also use `..` to filter for an inclusive range. When working with a range, `*` can be supplied as a wildcard operator.
160+
161+
| Qualifier | Example
162+
| ---------- | -------------
163+
| <code>field:<em>VALUE</em>..<em>VALUE</em></code> | **priority:1..3** will show items with a priority of 1, 2, or 3.
164+
| | **date:2022-01-01..2022-12-31** will show items from the year 2022.
165+
| | **points:\*..10** will show items with an points value of anything up to and including 10.
166+
| | **iteration:"Iteration 1".."Iteration 4"** will show items in "Iteration 1", "Iteration 2", "Iteration 3", and "Iteration 4."
167+
168+
### Filtering assignees and reviewers using keywords
169+
170+
You can use the `@me` keyword to represent yourself in a filter.
171+
172+
| Qualifier | Example
173+
| ---------- | -------------
174+
| <code>field:<em>@me</em></code> | **assignee:@me** will show items assigned to the signed-in user.
175+
| | **-reviewers:@me** will show items that have not been reviewed by the signed-in user.
176+
177+
### Filtering iteration and date fields using keywords
178+
179+
You can use the `@previous`, `@current`, and `@next` keywords to filter for iterations relative to the current iteration. You can also use `@today` to filter for the current day.
180+
181+
| Qualifier | Example
182+
| ---------- | -------------
183+
| <code>field:<em>@keyword<em></code> | **iteration:@current** will show items assigned to the current iteration.
184+
| | **iteration:@next** will show items assigned to the next iteration.
185+
| <code>field:<em>@today</em></code> | **date:@today** will show items with their date set to the current day.
186+
187+
You can also use `>`, `>=`, `<`, `<=`, `+`, `-`, and `..` ranges with keywords.
188+
189+
| Qualifier | Example
190+
| ---------- | -------------
191+
| <code>field:<em>@keyword</em>..<em>@keyword</em>+<em>n</em></code> | **iteration:@current..@current+3** will show items assigned to the current iteration and the next three iterations.
192+
| | **date:@today..@today+7** will show items with a date set to today or the next seven days.
193+
| <code>field:<<em>@keyword</em></code> | **iteration:<@current** will show items assigned to any iteration before the current iteration.
194+
| <code>field:>=<em>@keyword</em></code> | **date:>=@today** will show items with a date set to today or later.
195+
196+
### Filtering by text fields
197+
198+
You can filter by specific text fields or use a general text filter across all text fields and titles. When filtering with text that contains spaces or special characters, enclose your text in `"` or `'` quotation marks.
199+
200+
| Qualifier | Example
201+
| ---------- | -------------
202+
| <code>field:"<em>TEXT</em>" | **title:"API deprecation"** will show items with titles that exactly match "API deprecation."
203+
| <code>field:<em>TEXT</em> | **note:complete** will show items with a note text field that exactly match "complete."
204+
| <code><em>TEXT</em></code> | **API** will show items with "API" in the title or any other text field.
205+
| <code>field:<em>TEXT</em> TEXT | **label:bug rendering** will show items with the "bug" label and with "rendering" in the title or any other text field.
206+
207+
You can also use a <code>&ast;</code> as a wildcard.
208+
209+
| Qualifier | Example
210+
| ---------- | -------------
211+
| <code>field:&ast;<em>TEXT</em>&ast; | **label:&ast;bug&ast;** will show items with a label that contains the word "bug."
212+
| <code>field:<em>TEXT</em>&ast; | **title:API&ast;** will show items with a title that begins with "API."
213+
| <code>field:&ast;<em>TEXT</em> | **label:&ast;support** will show items with a label that ends with "support."

0 commit comments

Comments
 (0)