Issue is a client for reading and updating issues in a GitHub project issue tracker.
Issue runs the query against the given project's issue tracker and
prints a table of matching issues, sorted by issue summary.
The default owner/repo is golang/go.
If multiple arguments are given as the query, issue joins them by
spaces to form a single issue search. These two commands are equivalent:
Searches are always limited to open issues.
If the query is a single number, issue prints that issue in detail,
including all comments.
Issue expects to find a GitHub "personal access token" in
$HOME/.github-issue-token and will use that token to authenticate
to GitHub when reading or writing issue data.
A token can be created by visiting https://github.com/settings/tokens/new.
The token only needs the 'repo' scope checkbox, and optionally 'private_repo'
if you want to work with issue trackers for private repositories.
It does not need any other permissions.
The -token flag specifies an alternate file from which to read the token.
If the -a flag is specified, issue runs as a collection of acme windows
instead of a command-line tool. In this mode, the query is optional.
If no query is given, issue uses "state:open".
There are three kinds of acme windows: issue, issue creation, issue list,
search result, and milestone list.
The following text forms can be looked for (right clicked on)
and open a window (or navigate to an existing one).
Executing "New" opens an issue creation window.
Executing "Search <query>" opens a new window showing the
results of that search.
An issue window, opened by loading an issue number,
displays full detail about an issue, a header followed by each comment.
For example:
Executing "Get" reloads the issue data.
Executing "Put" updates an issue. It saves any changes to the issue header
and, if any text has been entered between the header and the "Reported by" line,
posts that text as a new comment. If both succeed, Put then reloads the issue data.
The "Closed" and "URL" headers cannot be changed.
An issue creation window, opened by executing "New", is like an issue window
but displays only an empty issue template:
Once the template has been completed (only the title is required), executing "Put"
creates the issue and converts the window into a issue window for the new issue.
An issue list window displays a list of all open issue numbers and titles.
If the project has any open milestones, they are listed in a header line.
For example:
As in any window, right clicking on an issue number opens a window for that issue.
A search result window, opened by executing "Search <query>", displays a list of issues
matching a search query. It shows the query in a header line. For example:
Executing "Sort" in a search result window toggles between sorting by title
and sorting by decreasing issue number.
Executing "Bulk" in an issue list or search result window opens a new
bulk edit window applying to the displayed issues. If there is a non-empty
text selection in the issue list or search result list, the bulk edit window
is restricted to issues in the selection.
The bulk edit window consists of a metadata header followed by a list of issues, like:
The metadata header shows only metadata shared by all the issues.
In the above example, all four issues are open and have milestone Go1.4.3,
but they have no common labels nor a common assignee.
The bulk edit applies to the issues listed in the window text; adding or removing
issue lines changes the set of issues affected by Get or Put operations.
Executing "Get" refreshes the metadata header and issue summaries.
Executing "Put" updates all the listed issues. It applies any changes made to
the metadata header and, if any text has been entered between the header
and the first issue line, posts that text as a comment. If all operations succeed,
Put then refreshes the window as Get does.
The milestone list window, opened by loading any of the names
"milestone", "Milestone", or "Milestones", displays the open project
milestones, sorted by due date, along with the number of open issues in each.
For example:
Loading one of the listed milestone names opens a search for issues
in that milestone.
The -e flag enables basic editing of issues with editors other than acme.
The editor invoked is $VISUAL if set, $EDITOR if set, or else ed.
Issue prepares a textual representation of issue data in a temporary file,
opens that file in the editor, waits for the editor to exit, and then applies any
changes from the file to the actual issues.
When <query> is a single number, issue -e edits a single issue.
See the “Issue Window” section above.
If the <query> is the text "new", issue -e creates a new issue.
See the “Issue Creation Window” section above.
Otherwise, for general queries, issue -e edits multiple issues in bulk.
See the “Bulk Edit Window” section above.
The -json flag causes issue to print the results in JSON format
using these data structures:
If asked for a specific issue, the output is an Issue with Comments.
Otherwise, the result is an array of Issues without Comments.