Skip to content

Commit 7a720df

Browse files
BagToadCopilotam-stead
authored
Add gh CLI documentation for Issues 2.0 (sub-issues, types, dependencies) (#61577)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>
1 parent bc9daf4 commit 7a720df

5 files changed

Lines changed: 211 additions & 16 deletions

File tree

‎content/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,26 @@ You can add up to {% data variables.projects.sub-issue_limit %} sub-issues per p
4545
* Select an issue from one of the suggestions.
4646
* In the "Search issues" field, type an issue title or issue number, then click on the results.
4747
* To add issues from other repositories, click {% octicon "arrow-left" aria-label="Back to repository selection" %} next to the repository name and select a different repository.
48+
49+
## Working with sub-issues using {% data variables.product.prodname_cli %}
50+
51+
{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli).
52+
53+
To create a new issue as a sub-issue of an existing parent, use the `--parent` flag with `gh issue create`. The parent can be specified by issue number or URL.
54+
55+
```shell
56+
gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION" --parent PARENT-ISSUE-NUMBER
57+
```
58+
59+
To add existing issues as sub-issues of a parent, use the `--add-sub-issue` flag with `gh issue edit`. The flag accepts a comma-separated list of issue numbers or URLs.
60+
61+
```shell
62+
gh issue edit PARENT-ISSUE-NUMBER --add-sub-issue SUB-ISSUE-NUMBER
63+
```
64+
65+
To remove a sub-issue from its parent, use `--remove-sub-issue` on the parent or `--remove-parent` on the sub-issue.
66+
67+
```shell
68+
gh issue edit PARENT-ISSUE-NUMBER --remove-sub-issue SUB-ISSUE-NUMBER
69+
gh issue edit SUB-ISSUE-NUMBER --remove-parent
70+
```

‎content/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,40 @@ When you view a sub-issue, you can always find a link back to the parent issue i
2828
## Using sub-issues in your projects
2929

3030
You can add sub-issues to your projects and make use of the hierarchy data for building views, grouping items, and filtering your views. See [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields).
31+
32+
## Browsing issue hierarchy with {% data variables.product.prodname_cli %}
33+
34+
{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli).
35+
36+
To view a parent issue along with its sub-issues, use the `gh issue view` subcommand.
37+
38+
```shell
39+
gh issue view ISSUE-NUMBER
40+
```
41+
42+
The output includes the parent reference (if any) and a "Sub-issues" section that lists each sub-issue with its state and completion progress.
43+
44+
```text
45+
Build a scoreboard octo-org/octo-repo#123
46+
Feature · Open • monalisa opened 3 days ago • 2 comments
47+
Assignees: monalisa
48+
Labels: enhancement
49+
Type: Feature
50+
51+
52+
Track player scores across rounds.
53+
54+
55+
Sub-issues · 1/3 (33%)
56+
Closed octo-org/octo-repo#124 Design scoreboard layout
57+
Open octo-org/octo-repo#125 Persist scores between sessions
58+
Open octo-org/octo-repo#126 Add a leaderboard view
59+
60+
View this issue on GitHub: https://github.com/octo-org/octo-repo/issues/123
61+
```
62+
63+
To get the same information in a machine-readable form, use the `--json` flag with the `parent`, `subIssues`, and `subIssuesSummary` fields.
64+
65+
```shell
66+
gh issue view ISSUE-NUMBER --json parent,subIssues,subIssuesSummary
67+
```

‎content/issues/tracking-your-work-with-issues/using-issues/creating-an-issue.md‎

Lines changed: 46 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -48,22 +48,6 @@ Issues can be used to keep track of bugs, enhancements, or other requests. For m
4848
{% data reusables.repositories.assign-an-issue-as-project-maintainer %}
4949
{% data reusables.repositories.submit-new-issue %}
5050

51-
## Creating an issue with {% data variables.product.prodname_cli %}
52-
53-
{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli).
54-
55-
To create an issue, use the `gh issue create` subcommand. To skip the interactive prompts, include the `--body` and the `--title` flags.
56-
57-
```shell
58-
gh issue create --title "My new issue" --body "Here are more details."
59-
```
60-
61-
You can also specify assignees, labels, milestones, and projects.
62-
63-
```shell
64-
gh issue create --title "My new issue" --body "Here are more details." --assignee @me,monalisa --label "bug,help wanted" --project onboarding --milestone "learning codebase"
65-
```
66-
6751
## Creating an issue from a comment
6852

6953
You can open a new issue from a comment in an issue or pull request. When you open an issue from a comment, the issue contains a snippet showing where the comment was originally posted.
@@ -152,6 +136,52 @@ Query parameter | Example
152136
You can also use URL query parameters to fill custom text fields that you have defined in issue form templates. Query parameters for issue form fields can also be passed to the issue template chooser. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#keys).
153137
{% endif %}
154138

139+
## Creating an issue with {% data variables.product.prodname_cli %}
140+
141+
{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli).
142+
143+
To create an issue, use the `gh issue create` subcommand. To skip the interactive prompts, include the `--body` and the `--title` flags.
144+
145+
```shell
146+
gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION"
147+
```
148+
149+
You can also specify assignees, labels, milestones, and projects.
150+
151+
```shell
152+
gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION" --assignee @me,USERNAME --label "LABEL-1,LABEL-2" --project PROJECT-NAME --milestone "MILESTONE-NAME"
153+
```
154+
155+
{% ifversion issue-types %}
156+
157+
To set the issue type, use the `--type` flag.
158+
159+
```shell
160+
gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION" --type "ISSUE-TYPE"
161+
```
162+
163+
{% endif %}
164+
165+
{% ifversion sub-issues %}
166+
167+
To create the issue as a sub-issue of an existing parent, use the `--parent` flag with an issue number or URL.
168+
169+
```shell
170+
gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION" --parent PARENT-ISSUE-NUMBER
171+
```
172+
173+
{% endif %}
174+
175+
{% ifversion fpt or ghec %}
176+
177+
To create dependencies at the same time, use the `--blocked-by` and `--blocking` flags. Both accept a comma-separated list of issue numbers or URLs.
178+
179+
```shell
180+
gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION" --blocked-by BLOCKED-BY-ISSUE-NUMBER --blocking BLOCKING-ISSUE-NUMBER
181+
```
182+
183+
{% endif %}
184+
155185
{% ifversion copilot %}
156186

157187
## Creating an issue with {% data variables.copilot.copilot_chat_short %} on {% data variables.product.github %}

‎content/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,41 @@ Blocked issues are marked with a "Blocked" icon on your project boards or reposi
3232
* To indicate that your issue no longer depends on another issue being completed, select **Change blocked by**.
3333
* To indicate that your issue is no longer preventing another issue from being completed, select **Change blocking**.
3434
1. In the dialog box that opens, deselect the issues that are no longer blocked by, or blocking, your issue.
35+
36+
## Managing issue dependencies with {% data variables.product.prodname_cli %}
37+
38+
{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli).
39+
40+
To create a new issue with dependencies, use the `--blocked-by` and `--blocking` flags on `gh issue create`. Each flag accepts a comma-separated list of issue numbers or URLs.
41+
42+
```shell
43+
gh issue create --title "TITLE" --body "ISSUE-DESCRIPTION" --blocked-by BLOCKED-BY-ISSUE-NUMBER --blocking BLOCKING-ISSUE-NUMBER
44+
```
45+
46+
To add or remove dependencies on an existing issue, use the corresponding flags on `gh issue edit` with the issue number or URL.
47+
48+
```shell
49+
gh issue edit ISSUE-NUMBER --add-blocked-by BLOCKED-BY-ISSUE-NUMBER --add-blocking BLOCKING-ISSUE-NUMBER
50+
gh issue edit ISSUE-NUMBER --remove-blocked-by BLOCKED-BY-ISSUE-NUMBER --remove-blocking BLOCKING-ISSUE-NUMBER
51+
```
52+
53+
To see an issue's dependencies, use `gh issue view`. The output includes "Blocked by" and "Blocking" rows when relationships are set.
54+
55+
```text
56+
My new issue octo-org/octo-repo#123
57+
Open • monalisa opened 3 days ago • 0 comments
58+
Blocked by: octo-org/octo-repo#200 Database schema migration
59+
Blocking: octo-org/octo-repo#300 Release v2.0
60+
61+
62+
Here are more details.
63+
64+
65+
View this issue on GitHub: https://github.com/octo-org/octo-repo/issues/123
66+
```
67+
68+
You can also access dependencies programmatically with the `--json` flag using the `blockedBy` and `blocking` fields.
69+
70+
```shell
71+
gh issue view ISSUE-NUMBER --json blockedBy,blocking
72+
```

‎content/issues/tracking-your-work-with-issues/using-issues/editing-an-issue.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,73 @@ You can add an issue type or make changes to an existing issue type.
5252

5353
{% endif %}
5454

55+
## Editing an issue with {% data variables.product.prodname_cli %}
56+
57+
{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli).
58+
59+
### Editing a single issue
60+
61+
To edit an issue, use the `gh issue edit` subcommand with the issue number or URL.
62+
63+
```shell
64+
gh issue edit ISSUE-NUMBER --title "TITLE" --body "ISSUE-DESCRIPTION"
65+
```
66+
67+
### Editing multiple issues
68+
69+
You can pass multiple issue numbers to apply the same change to several issues at once.
70+
71+
```shell
72+
gh issue edit ISSUE-NUMBER-1 ISSUE-NUMBER-2 --add-label "LABEL"
73+
```
74+
75+
{% ifversion issue-types %}
76+
77+
### Editing the issue type
78+
79+
To set or remove the issue type, use the `--type` or `--remove-type` flag.
80+
81+
```shell
82+
gh issue edit ISSUE-NUMBER --type "ISSUE-TYPE"
83+
gh issue edit ISSUE-NUMBER --remove-type
84+
```
85+
86+
{% endif %}
87+
88+
{% ifversion sub-issues %}
89+
90+
### Editing the parent issue
91+
92+
To set or remove the parent issue, use the `--parent` or `--remove-parent` flag. The parent can be specified by issue number or URL.
93+
94+
```shell
95+
gh issue edit ISSUE-NUMBER --parent PARENT-ISSUE-NUMBER
96+
gh issue edit ISSUE-NUMBER --remove-parent
97+
```
98+
99+
### Editing sub-issues
100+
101+
To add or remove sub-issues, use the `--add-sub-issue` or `--remove-sub-issue` flag with a comma-separated list of issue numbers or URLs.
102+
103+
```shell
104+
gh issue edit PARENT-ISSUE-NUMBER --add-sub-issue SUB-ISSUE-NUMBER
105+
gh issue edit PARENT-ISSUE-NUMBER --remove-sub-issue SUB-ISSUE-NUMBER
106+
```
107+
108+
{% endif %}
109+
110+
{% ifversion fpt or ghec %}
111+
112+
### Editing dependencies
113+
114+
To manage dependencies, use the `--add-blocked-by`, `--remove-blocked-by`, `--add-blocking`, and `--remove-blocking` flags. Each accepts a comma-separated list of issue numbers or URLs.
115+
116+
```shell
117+
gh issue edit ISSUE-NUMBER --add-blocked-by BLOCKED-BY-ISSUE-NUMBER --add-blocking BLOCKING-ISSUE-NUMBER
118+
```
119+
120+
{% endif %}
121+
55122
## Further reading
56123

57124
* [AUTOTITLE](/issues/tracking-your-work-with-issues/administering-issues/closing-an-issue)

0 commit comments

Comments
 (0)