# What is Jasper
A flexible and powerful issue reader for GitHub
[Jasper](https://jasperapp.io/) is a tool that allows you to view GitHub issues and pull requests with flexible criteria. For example, you can browse issues and receive update notifications for issues with conditions such as "pull requests you create" or "issues with a nodejs/node bug label".
We call this functionality **"Stream"** in Jasper, and we can set up a Stream with the following query to view an issue with the conditions described above
```
author:defunkt is:pr
```
```
repo:nodejs/node label:bug is:issue
```
## Stream
Stream is powered by the [GitHub Search API](https://docs.github.com/en/rest/reference/search), which allows you to use very powerful queries. For example, the following query.
| 条件 | クエリ |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Issue created by defunkt | [`author:defunkt is:issue`](https://github.com/search?q=author%3Adefunkt+is%3Aissue) |
| pull request in the nodejs/node repository | [`repo:nodejs/node is:pr`](https://github.com/search?q=repo%3Anodejs%2Fnode+is%3Apr) |
| Issue/pull request with a bug label in a nodejs organization | [`org:nodejs label:bug`](https://github.com/search?q=org%3Anodejs+label%3Abug) |
And since Stream can use the exact same queries as the GitHub Search API, you have the flexibility to browse issues you are interested in.
{% hint style="info" %}
See "[Stream queries](/usecase/query)" and "[Stream](/reference/stream)" for a list of queries that can be used with Stream.
{% endhint %}
## High flexibility
Currently, there are several tools for viewing GitHub issues, which fall into three main categories
1. Tools to manage issue viewing and notifications\
[GitHub Notifications](https://github.com/notifications), [DevHub](https://devhubapp.com/), [Trailer](http://ptsochantaris.github.io/trailer/) and more
2. Tools for Team Collaboration\
[GitHub Scheduled reminders](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/managing-scheduled-reminders-for-your-team), [Pull Panda](https://pullpanda.com/) and more
3. Tools for project management\
[GitHub Projects](https://docs.github.com/en/github/managing-your-work-on-github/managing-project-boards), [Zen Hub](https://www.zenhub.com/) and more
Jasper is a tool that belongs to category 1. Normally, tools in this category use the [GitHub Notification API](https://docs.github.com/en/rest/reference/activity#notifications). However, Jasper is built using the [GitHub Search API](https://docs.github.com/en/rest/reference/search), which gives it a lot of flexibility not found in other tools. On the other hand, it may not be as easy to use as other tools. That's why Jasper has been developed with a balance between flexibility and simplicity in mind.
{% hint style="info" %}
See "[Concept](/faq#concept)" for more information.
{% endhint %}
# Quick start
If you are new to Jasper, please read "[Setup](/quick-start/setup)" and "[Basic Usage](/quick-start/basic-usage)".
If you are already using Jasper and want to migrate your data to the new environment, please read the "[Data Migration](/quick-start/data-migration)" section.
# Setup
Just download Jasper and set up a GitHub access token and you're ready to go.
## Install
Download the latest version of Jasper from [jasperapp.io](https://jasperapp.io/) and extract the zip file. Follow the instructions to complete the launch.
{% tabs %}
{% tab title="Mac" %}
{% endtab %}
{% tab title="Windows" %}
{% endtab %}
{% endtabs %}
## Setting up an access token
When Jasper is launched, you will be presented with a choice of GitHub or GHE (GitHub Enterprise), for GHE enter the hostname `example ghe.example.com`.
Next, you will need to enter an access token, which differs between GitHub and GHE.
{% tabs %}
{% tab title="For GitHub" %}
For GitHub, we recommend setting up an access token using OAuth. Please follow the on-screen instructions to perform OAuth authentication.
Alternatively, an access token can be created and used from a [Personal access token](https://github.com/settings/tokens). The required scopes are `repo`, `read:org`, `notifications`, `user` and `read:project` .
{% endtab %}
{% tab title="For GHE" %}
For GHE, you can create an access token from `https://GHE_HOST/settings/tokens`. The required scopes are `repo`, `read:org`, `notifications`, `user` and `read:project` .
{% endtab %}
{% endtabs %}
Finally, confirm the settings and press OK. When the user name is displayed, you are done 🎉.
## Initial loading
Once the setup is complete, the system will automatically start loading the issue. This initial loading takes a few minutes or so - do not exit Jasper and use it.
To help you get started with Jasper, please read the "[Basic Usage](/quick-start/basic-usage)" section during the initial loading process.
# Basic usage
Here's a basic guide to using Jasper. Just the basics are enough to help you learn how to use it, and then you will be able to browse issues efficiently.
## Stream
After setup, it will automatically create Streams.
| Stream | description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Me` | You can see issues/pull requests that are relevant to you. Basically, you won't miss anything if you look at this Stream. You can also filter by `My Issues` or `My PRs`. |
| `My Issues` | Issue I was creating |
| `My PRs` | Pull request you created |
| `Assigned` | Issue/pull request to which you are assigned |
| `Review Requested` | Review requested pull request |
In addition, the following notice will appear after a while. Follow the instructions to create other streams.
## issues
The following operations are particularly useful for viewing issues
| action | How to operate |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Show only unread issues | Select Filter by unread in the filter menu.
Or press U on the keyboard.
|
| Set the issue back to unread | Click the unread icon on the floating menu.
Or press I on the keyboard.
|
{% tabs %}
{% tab title="Filter menu" %}
{% endtab %}
{% tab title="Floating menu" %}
{% endtab %}
{% endtabs %}
## Browser
Comments that have been added or updated since the last time you viewed the site will be highlighted.
{% hint style="info" %}
For more information on how to use it, please refer to "[Use cases](/usecase)" and "[Reference](/reference)".
{% endhint %}
# Data migration
You can migrate your Jasper data to the new machine.
## 1. Save existing data
Start Jasper on the old machine and select `Menu → Jasper → Export Data`.
Click `Open data directory` to display the directory. Copy the `config.json` and `main.db` in the directory displayed to your desktop. Move these data to your new machine using Google Drive or Dropbox etc.
{% hint style="info" %}
If you have multiple accounts registered in Jasper, you will also need to copy a file such as `main-123456789.db`.
{% endhint %}
## 2. Migrate data to the new machine
Start Jasper on a new machine. On the first configuration screen, select `Import Data`.
Click on the `Open data directory` to display the directory. Copy (overwrite) the `config.json` and `main.db` that you just moved into this directory. Finally, click on `Restart Jasper` and your data migration is complete.
# Use cases
# Stream queries
Stream allows you to specify flexible queries. Here are some of the most commonly used queries.
## Open issues
You can use `is:open` to create a Stream to view issues in an open (unclosed or unmerged) state. For example, to view an open issue in the `nodejs/node` repository, you can create a Stream with the following query
```
repo:nodejs/node is:open is:issue
```
However, Jasper does not recommend using `is:open` to create a Stream because Jasper will not be able to detect when the Stream is closed from open to closed.
{% hint style="info" %}
This is a limitation of Jasper's polling of the GitHub Search API
{% endhint %}
So when using `is:open`, you should use the Filter Stream instead of the regular Stream. Filter Stream can be used to apply custom filters to a normal Stream. In the previous example, this would look like
Stream
```
repo:nodejs/node is:issue
```
Filter Stream
```
is:open
```
{% hint style="info" %}
For more information about Filter Stream, see "[Filter Stream](/reference/filter-stream)" in the reference.
{% endhint %}
{% hint style="info" %}
The same restrictions apply to close, merge and draft states.
{% endhint %}
## Team mentioned issues
To view Team mentioned issues, use `team:ORGNAME/TEAMNAME`. For example, to view issues where `@jekyll/owners` are mentioned, create a Stream with a query like this
```
team:@jekyll/owners
```
GitHub Docs: [Search by team mention](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-team-mention)
## User involved issues
To view issues involving a particular user, use the `involves:USERNAME`. For example, to see the issues involving a `defunkt` or `jlord`, create a Stream with a query like this
```
involves:defunkt OR involves:jlord
```
{% hint style="info" %}
The `involves:USERNAME` is a useful query to specify author, assign, mention, comment, and review-requested all together.
{% endhint %}
GitHub Docs: [Search by a user that's involved in an issue or pull request](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-a-user-thats-involved-in-an-issue-or-pull-request)
## Repository and organization issues
To view issues in a specific repository, use `repo:USERNAME/REPOSITORY`. For example, to view issues in the `nodejs/node` or `electron/electron` repositories, you would create a Stream with a query like this
```
repo:nodejs/node OR repo:electron/electron
```
To view a specific Organization issue, use `org:ORGNAME`. For example, to view issues of the `nodejs` or `electron` Organization, you can create a Stream with a query like this
```
org:nodejs OR org:electron
```
GitHub Docs: [Search within a user's or organization's repositories](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-within-a-users-or-organizations-repositories)
## Issues with milestones and labels
You can view issues with a specific milestone by using `milestone:MILESTONE_NAME`. For example, to see an issue with a milestone of `13.0.0` or `14.0.0` in the `nodejs/node` repository, create a Stream with a query like this
```
repo:nodejs/node ( milestone:13.0.0 OR milestone:14.0.0 )
```
You can view issues labeled with a specific label using `label:LABEL_NAME`. For example, to view an issue labeled `build` **and** `zlib` in the `nodejs/node` repository, create a Stream with the following query
```
repo:nodejs/node label:build label:zlib
```
{% hint style="info" %}
If multiple labels are specified, it is an and condition.
{% endhint %}
{% hint style="info" %}
For milestones and labels that contain spaces, specify them as `milestone: "foo bar"`.
{% endhint %}
GitHub Docs: [Search by milestone](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-milestone), [Search by label](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-label)
## Issues containing the keywords
To view issues containing specific keywords, use the `KEYWORD`. For example, to see issues containing the `octocat` and `github`, create a Stream with the following query
{% tabs %}
{% tab title="AND condition" %}
```
octocat github
```
{% endtab %}
{% tab title="OR condition" %}
```
octocat OR github
```
{% endtab %}
{% tab title="NOT condition" %}
```
octocat NOT github
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Keywords including multi-byte characters and spaces should be specified as `"foo bar"`.
{% endhint %}
GitHub Docs: [Limitations on query length](https://docs.github.com/en/github/searching-for-information-on-github/troubleshooting-search-queries#limitations-on-query-length), [Exclude certain results](https://docs.github.com/en/github/searching-for-information-on-github/understanding-the-search-syntax#exclude-certain-results)
## Exclusionary specification
You can use `-QUALIFIER` to exclude a specific repository, label or etc . For example, to view issues in the `nodejs` organizaton that do not contain a `nodejs/node` repository and a `bug` label, you can create a Stream with a query like this
```
org:nodejs -repo:nodejs/node -label:bug
```
GitHub Docs: [Exclude certain results](https://docs.github.com/en/github/searching-for-information-on-github/understanding-the-search-syntax#exclude-certain-results)
# Browse issues
There are a number of features available in Jasper to help you browse issues efficiently. Here are some of the most commonly used features.
## Unread issues
To quickly display just the unread issues, use the issue's filter function - select `Filter by unread` from the filters at the top of the issue list. Alternatively, you can also display just the unread issues by pressing `U` on your keyboard.
## Read it later
If you want to read it later, there are two ways to do it in Jasper.
The first is to return an issue to unread by selecting `Mark as Unread` from the issue's floating menu. Alternatively, you can press `I` on the keyboard on a selected issue to mark it back as unread.
The second way to bookmark an issue is to add it to your bookmarks. Select `Add to Bookmark` from the issue's floating menu. Alternatively, you may bookmark a selected issue by pressing `B` on the keyboard.
{% tabs %}
{% tab title="Mark as unread" %}
{% endtab %}
{% tab title="Add to bookmark" %}
{% endtab %}
{% endtabs %}
## Exclude unwanted issues
You can use the archive feature to exclude issues that you do not need to view in the future. To archive, select `Move to Archive` from the floating menu. Alternatively, you may archive an issue in the selected state by pressing the `E` key on your keyboard.
## Check unread comments
When viewing an issue in Jasper's built-in browser, Jasper will highlight the comments that have been added or updated since the last time you viewed the issue. You will also see a mini-map of the comments that have been added/updated on the left side of the issue. You can use this comment highlighting and minimap to quickly see which comments have not been read.
{% tabs %}
{% tab title="Highlight comments" %}
{% endtab %}
{% tab title="Comment minimap" %}
{% endtab %}
{% endtabs %}
Also, any updates to the body of the issue will be displayed as a differential.
{% tabs %}
{% tab title="Notice of difference" %}
{% endtab %}
{% tab title="Show the difference" %}
{% endtab %}
{% endtabs %}
# Search issues
You can search for issues in the Stream or in their entirety.
## Search from Stream
To search for an issue from a given Stream, use the `Filter` function, click on the filter icon at the top of the issue list.
{% hint style="info" %}
You can use the same filters as Filter Stream to search in Filter. See "[Filter Stream](/reference/filter-stream)" in the reference section for more information.
{% endhint %}
## Search from All
To search through Jasper's holdings of issues, we use the `Jump Navigation` feature, starting with the 🔍 icon in the top left corner. You can also start by pressing `⌘ + K (Mac)`, `Ctrl + K (Window/Linux)`.
{% hint style="info" %}
You can use the same filters as Filter Stream to search in Jump Navigation. See "[Filter Stream](/reference/filter-stream)" in the reference section for more information.
{% endhint %}
# Appearance and notifications
You can configure appearance and notifications of each Stream to make it easier to use.
## Stream colors and notification settings
Streams can be configured with colors and icons in the detail settings. This allows for grouping and allows you to make important Streams stand out from the crowd.
Notifications can also be turned on or off per Stream. If you don't want to be notified, you can turn off notifications for the streams you don't want to be notified about, so you don't miss any important notifications. Notifications can also be configured in batches from the Preferences screen.
{% tabs %}
{% tab title="Stream details" %}
{% endtab %}
{% tab title="Collective setting" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Icons are available for all types of icons registered in [Material Design Icons](https://materialdesignicons.com/).
{% endhint %}
## General notification settings
You can also turn off notifications for the entire issue if you want to focus on viewing the issue. You can turn notifications on/off by clicking the 🔔 icon in the top left corner. Or you can press `⌘ + I`.
## Change the layout
You can increase the display area of an issue if you have a small screen, or if you are doing a pull request code review. You can increase the display area by toggling the layout icon in the top right corner, or you can toggle it by pressing ⌘ + 1, ⌘ + 2, or ⌘ + 3. You can also switch between them by pressing `⌘ + 1`, `⌘ + 2`, or `⌘ + 3`.
{% tabs %}
{% tab title="Layout icon" %}
{% endtab %}
{% tab title="3 Layouts(normal)" %}
{% endtab %}
{% tab title="2 Layouts" %}
{% endtab %}
{% tab title="1 Layout" %}
{% endtab %}
{% endtabs %}
## Hide the Stream
You can also hide unwanted Streams. For example, if you don't use `Inbox` or `Archive`, you can hide them to make Jasper easier to see.
# Keyboard operation
Jasper provides a variety of keyboard shortcuts. Here are some of the most commonly used keyboard shortcuts.
## Commonly used keyboard shortcuts
| Action | Keyboard shortcut |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Show Jump Navigation | `⌘ + K`, `Ctrl + K` |
| Turn on/off notifications | `⌘ + I`, `Ctrl + I` |
| Change the layout | ⌘ + 1, ⌘ + 2, ⌘ + 3
Ctrl + 1, Ctrl + 2, Ctrl + 3
|
| Show unread issues | `U` |
| Show next/previous Stream | `D` , `F` |
| View next/previous issue | `J` , `K` |
| Scrolling in the browser | `Space`, `Shift + Space` |
{% hint style="info" %}
For all keyboard shortcuts, see "[Keyboard Shortcuts](/reference/keyboard-shortcut)".
{% endhint %}
{% hint style="info" %}
To customize the keyboard shortcuts, see "[Customizing the keyboard shortcuts (Mac)](/reference/keyboard-shortcut#customize)".
{% endhint %}
# Advanced settings
Integration with GitHub's features allows for more advanced usage.
## Smartphone integration
You must enable GitHub Notification Sync in order for Jasper to read issues viewed on a smartphone or normal browser.
By enabling this setting, [GitHub Notifications](https://github.com/notifications) will periodically (usually at 60-second intervals) reflect this to Jasper.
{% hint style="warning" %}
Jasper will only reflect the issue in GitHub Notifications if you have "Viewed and marked the issue as read". The following operations will not be reflected in GitHub Notifications
* Unread issues in Jasper
* Issues read using a menu or keyboard shortcut in Jasper
{% endhint %}
## GitHub Projects Integration
To view issues related to a specific Github Project, create a Project Stream.
{% tabs %}
{% tab title="Creating a Project Stream" %}
{% endtab %}
{% tab title="View Project Stream" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
With the `project:REPOSITORY/PROJECT_BOARD` query, you can still create a regular Stream to view issues related to GitHub Projects. However, we recommend using Project Stream as it allows you to work with the Project Board (Kanban).
{% endhint %}
## GitHub Team Integration
Use the Team Stream to view issues that have been mentioned to your GitHub Team.
{% tabs %}
{% tab title="Enable Team Stream" %}
{% endtab %}
{% tab title="Team Stream" %}
{% endtab %}
{% tab title="Team Stream queries" %}
Queries are automatically created from the Team you belong to.
{% endtab %}
{% endtabs %}
## GitHub Watching Integration
You can use the Watching Stream to view issues in repositories that you have watched on GitHub.
{% tabs %}
{% tab title="Enable Watching Stream" %}
{% endtab %}
{% tab title="Watching Stream" %}
{% endtab %}
{% tab title="Watching Stream queries" %}
Queries are automatically created from the repositories you watch.
{% endtab %}
{% endtabs %}
## Register any issues
If you want the issue to be a Stream on its own, rather than a repository or organization, use the Subscription Stream, which you enable from the configuration screen.
{% tabs %}
{% tab title="Enable Subscription Stream" %}
{% endtab %}
{% tab title="Subscription Stream" %}
{% endtab %}
{% tab title="Register issue" %}
Right-click on the Subscription Stream and register the URL of the issue in the menu.
{% endtab %}
{% endtabs %}
## Optimizing the update interval
Jasper typically looks for an issue every 10 seconds to get an update. This update interval is not per Stream, but rather for the entire Jasper. This means that the more Streams you create, the slower the update per Stream will be. For example, if you are creating three Streams, a Stream will only be updated every 30 seconds.
{% hint style="info" %}
The reason it works this way is so that more Streams don't overload GitHub.
{% endhint %}
This is why creating a lot of Streams can slow down updates. So we use fewer regular Streams and more Filter Streams, so that updates are not slowed down.
{% hint style="info" %}
Filter Stream does not search GitHub and filters local issues, so it does not affect the update interval. For more information on Filter Stream, see "[Filter Stream](/reference/filter-stream)".
{% endhint %}
For example, instead of creating two Streams, create a Stream and two Filter Streams, like this This will allow you to update at 10 second intervals per stream, instead of 20 seconds per stream in the former.
{% tabs %}
{% tab title="Two Streams" %}
```
org:nodejs
```
```
org:electron
```
{% endtab %}
{% tab title="A Stream and two Filter Streams" %}
```
org:nodejs org:electron
```
```
org:nodejs
```
```
org:electron
```
{% endtab %}
{% endtabs %}
Jasper recommends using Filter Stream actively in this way.
# Reference
# Stream
A query reference that can be used for Stream.
Streams can be added from the `Add Stream` menu.
{% tabs %}
{% tab title="Add Stream" %}
{% endtab %}
{% tab title="Stream setting" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
The queries available in Stream are fully compatible with GitHub Search queries.\
See "[Searching issues and pull requests - github.com](https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-issues-and-pull-requests)"and "[Understanding the search syntax - github.com](https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/understanding-the-search-syntax)" for all GitHub Search queries and syntax.
{% endhint %}
## State of issues
| Query | description |
| --------------------------------------------------------------------------------------- | ------------------------------ |
| `is:issue`, `is:pr` | Issue only, pull request only |
| is:open, is:closed
not recommended
| Opened issues, closed issues |
| is:merged, is:unmerged
not recommended
| Merged issues, unmerged issues |
| draft:true, draft:false
not recommended
| Draft issues, not draft issues |
{% hint style="warning" %}
Open, merge and draft state queries are not recommended. If you use these queries, use Filter Stream. See [here](/usecase/query#open-issue) for more information.
{% endhint %}
## Involve users and teams
| Query | description |
| -------------------- | --------------------- |
| `involves:defunkt` | User involved issues |
| `author:defunkt` | User created issues |
| `assignee:defunkt` | User assigned issues |
| `mentions:defunkt` | User mentioned issues |
| `commenter:defunkt` | User commented issues |
| `team:github/owners` | Team mentioned issues |
{% hint style="info" %}
Multiple queries of the same type become OR conditions. For example, `Involves:defunkt involves:jlord` is issues involving `defunkt` or `jlord`.
{% endhint %}
{% hint style="info" %}
`involves` as well as `author`, `assignee`, `mentions`, `commenter`, and `review-requested` all together.
{% endhint %}
## Pull requests review
| Query | description |
| --------------------------------------------- | -------------------------------------------------------------------- |
| `review-requested:defunkt` | Pull requests where the user has requested a review |
| `team-review-requested:github/owners` | Pull requests for which the team has requested a review |
| `reviewed-by:defunkt` | User reviewed pull requests |
| `review:approved`, `review:changes_requested` | Approved pull requests,
Changes requested pull requests
|
{% hint style="info" %}
Multiple queries of the same type become OR conditions. For example, `review-requested:defunkt review-requested:jlord` is pull requests where `defunk` or `jlord` is the review request.
{% endhint %}
## Repository and organization
| Query | description |
| ------------------ | ------------------- |
| `repo:nodejs/node` | Repository issues |
| `org:nodejs` | Organization issues |
| `user:defunkt` | User issues |
{% hint style="info" %}
Multiple queries of the same type will result in OR conditions. For example, `repo:nodejs/node repo:electron/electron` is issues `nodejs/node` or `electron/electron`.
{% endhint %}
## Labels, milestones, etc.
| Query | description |
| --------------------------- | --------------------------- |
| `label:bug` | Labeled issues |
| `milestone:v1.0.0` | Milestone issues |
| `project:github/57` | Organization project issues |
| `project:github/linguist/1` | Repository project issues |
{% hint style="info" %}
More than one query of the same type is an OR condition. For example, `milestone:v1.0.0.0 milestone:v2.0.0` is an issue with a `v1.0.0` or `v2.0.0.0` milestone. However, this is an AND condition for labels.
{% endhint %}
{% hint style="info" %}
A label or milestone containing spaces should be enclosed in double quotes, such as `label: "hello world"`.
{% endhint %}
## Any keywords
| Query | description |
| -------------------- | ----------------------------------------------- |
| `github octocat` | Issues containing the keywords (AND conditions) |
| `github OR octocat` | Issues containing the keyword (OR condition) |
| `github NOT octocat` | Issues containing the keywords (NOT conditions) |
{% hint style="info" %}
To include spaces, use double quotation marks, such as `"hello world"`.
{% endhint %}
{% hint style="info" %}
AND, OR, and NOT can only contain up to five query lengths. See "[Limitations on query length - github.com](https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/troubleshooting-search-queries#limitations-on-query-length)" for more information.
{% endhint %}
## Exclusion and missing
| Query | description |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| -label:bug
-milestone:v0.0.1
-repo:nodejs/node
-involves:defunk
and more
| Issues that do not contain the specified conditions |
| no:label
no:milestone
no:assignee
no:project
| Labels, Milestones, Assignments,
and An issue with no project set up
|
# Filter Stream
This is a reference for the filters available in Filter Stream.
Filter Stream filters the Stream's issues and displays them.
Filter Streams are added from the `Add Filter Stream` menu in the Stream menu. Or, to create a top-level stream, add it from the `Add Filter Stream top-level` menu. It is also possible to apply a Filter temporarily.
{% tabs %}
{% tab title="Add Filter Stream" %}
{% endtab %}
{% tab title="Filter Stream setting" %}
{% endtab %}
{% tab title="Add Top Level Filter Stream" %}
{% endtab %}
{% tab title="Temporarily" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
The filters available in the Filter Stream are pretty much the same as in the Stream, but note that some of them are slightly different.
{% endhint %}
## State of issues
| Filter | description |
| ------------------------------ | -------------------------------------------------------- |
| `is:issue`, `is:pr` | Issues only, pull requests only |
| `is:open`, `is:closed` | Opened issues, closed issues |
| `is:merged`, `is:unmerged` | Merged issues, unmerged issues |
| `draft:true`, `draft:false` | Draft issues, not draft issues |
| `is:read`, `is:unread` | Read issues, unread issues |
| `is:bookmark`, `is:unbookmark` | Bookmarked issues, not bookmarked issue |
| `is:archived`, `is:unarchived` | Archived issues, not archived issues |
| `is:private`, `is:unprivate` | Private repository issues, not private repository issues |
## Involve users and teams
| Filter | description |
| -------------------- | --------------------- |
| `involves:defunkt` | User involved issues |
| `author:defunkt` | User created issues |
| `assignee:defunkt` | User assigned issues |
| `mentions:defunkt` | User mentioned issues |
| `team:github/owners` | Team mentioned issues |
{% hint style="info" %}
Multiple filters of the same type can be specified as OR conditions. For example, `involves:defunkt involves:jlord` is issues involving `defunkt` or `jlord`.
{% endhint %}
{% hint style="info" %}
`involves` as well as `author`, `assignee`, `mentions`,`commenter` and `review-requested` all together.
{% endhint %}
## Pull requests review
| Filter | description |
| -------------------------- | -------------------------------------------------------- |
| `review-requested:defunkt` | Pull requests where the user/team has requested a review |
| `reviewed-by:defunkt` | User reviewed pull requests |
{% hint style="info" %}
Specifying multiple queries of the same type is an OR condition. For example, `review-requested:defunkt review-requested:jlord` is pull requests where `defunkt` or `jlord` is the review request.
{% endhint %}
## Repository and Organization
| Filter | description |
| ------------------ | ------------------- |
| `repo:nodejs/node` | Repository issues |
| `org:nodejs` | Organization issues |
| `user:defunkt` | User issues |
{% hint style="info" %}
Specifying multiple queries of the same type is an OR condition. For example, `repo:nodejs/node repo:electron/electron` is issues of `nodejs/node` or `electron/electron`.
{% endhint %}
## Label, milestone, etc
| Filter | description |
| -------------------------------------- | --------------------------------------------------------- |
| `label:bug`, `label:bug-%` | Labeled issues
% matches any string
|
| `milestone:v1.0.0`, `milestone:v2.0.%` | Milestone issues
% matches any string
|
| `title:test`, `title:%test%` | Issue with specified title
% matches any string
|
| `number:123` | Issue number |
Labels can also specify dynamic dates as follows.
| Filter | Description (assuming today is 2022-08-16) |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label:release_@current_date` | `@current_date` is replaced by the current date. In other words, `label:release_2022%08%16` is executed as a filter. |
| `label:release_@prev_date` | The `@prev_date` is replaced by yesterday's date. In other words, `label:release_2022%08%15` is executed as a filter. |
| `label:release_@next_date` | The `@next_date` is replaced by tomorrow's date. In other words, `label:release_2022%08%17` is executed as a filter. |
| `label:release_@current_date+1`, `label:release_@current_date-1` | Following `@current_date` with `+1` or `-1` replaces the date relative to the current date. So the filter will run `label:release_2022%08%17` or `label:release_2022%08%15`. |
{% hint style="info" %}
Specifying multiple queries of the same type is an OR condition. For example, `milestone:v1.0.0.0 milestone:v2.0.0` is issues with a `v1.0.0` or `v2.0.0.0` milestone. However, this is an AND condition for labels.
{% endhint %}
{% hint style="info" %}
A label or milestone containing spaces should be enclosed in double quotation marks, such as `label: "hello world"`.
{% endhint %}
## GitHub Project
| Filter | description |
| ----------------------------------------- | -------------------------------------------------- |
| `project-field:status/ToDo` | Issue whose status field is ToDo |
| `project-field:sprint/@current_iteration` | Issue whose sprint field is the current iteration. |
| `project-field:foo/bar` | Issue where the foo field is bar |
Below are the filters for the classic project.
| Filter | description |
| -------------------------------------------- | ---------------------------- |
| `project-name:hello-pj` (classic project) | Issues tied to the project |
| `project-column:now-doing` (classic project) | Issue tied to project column |
## Any keywords
| Filter | description |
| ---------------- | ----------------------------------------------- |
| `github octocat` | Issues containing the keywords (AND conditions) |
{% hint style="info" %}
To include spaces, use double quotation marks, such as `"hello world"`.
{% endhint %}
{% hint style="info" %}
Search keywords in issue body, author, assignee, label, milestone, repository, org, involves, review-requested, review, project-name and project-columns.
{% endhint %}
{% hint style="warning" %}
OR and NOT are not supported.
{% endhint %}
## Exclusion and missing
| Filter | Condition |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| -label:bug,
-milestone:v0.0.1,
-repo:nodejs/node ,
-involves:defunk ,
and more
| Issues that do not contain the specified conditions |
| no:label,
no:milestone,
no:assignee,
no:project,
no:dueon
| Labels, Milestones, Assignments,
and An issue with no project set up
|
| have:label,
have:milestone,
have:assignee,
have:project,
have:dueon
| Labels, Milestones, Assignments,
and An issue with project set up
|
# Project Stream
Project Stream reference.
You can specify a GitHub project you have been involved with in the "Suggest Project" section of the Project Stream. Alternatively, you can manually specify the URL of the GitHub Project.
{% tabs %}
{% tab title="Add Project Stream" %}
{% endtab %}
{% tab title="Project Stream setting" %}
{% endtab %}
{% endtabs %}
When you select Project Stream, the Project Board will automatically appear, and the issues on the Project Board will reflect the unread/read issues in Jasper.
# Library Stream
Library Stream reference.
The Library Stream is a cross-section of issues within Jasper. To use the Library Stream, go to the `Menu → Preferences → Streams` and enable it.
| Library Stream | description |
| -------------- | --------------------------------------- |
| `Inbox` | All issues that are not archived |
| `Open` | Open issues that are not archived |
| `Unread` | Unread issues that are not archived |
| `Bookmark` | Bookmarked issues that are not archived |
| `Archived` | Archived issues |
`Inbox`, `Bookmark`, and `Archived` are enabled by default.
# System Stream
System Stream reference.
System Stream is the system's built-in stream that generates queries dynamically; to use System Stream, go to `Menu → Preferences → Streams` and enable it.
| System Stream | description |
| -------------------- | ---------------------------------------------------- |
| `Team Stream` | Issues on GitHub where your team mentioned |
| `Watching Stream` | Issues in the repositories you're watching on GitHub |
| `Subscription Issue` | Individually registered issues |
The `Team Stream` allows you to get the teams you belong to on GitHub and handle issues where they are mentioned. When you join a new team, the team will be added automatically.
The `Watching Stream` can retrieve repositories that you have watched on GitHub and handle issues in those repositories. When you watch a new repository, it will automatically add it to your repository.
The `Subscription Stream` provides the ability to handle individually registered issues. Register the URL of the issue from the `Subscription Stream` menu.
# Sort order
A reference to the order of issues.
Typically, issues are displayed in order of update, and you can change the order by using the sort order icon at the top of the issue list. You may also change the order by setting the Filter Stream or Filter to `sort:ORDER`.
{% tabs %}
{% tab title="Changing the order" %}
{% endtab %}
{% tab title="Specify sort:ORDER for the filter" %}
{% endtab %}
{% endtabs %}
The following values can be specified for `sort:ORDER`.
| sort | description |
| ---------------- | --------------------------------------- |
| `sort:updated` | Updated order |
| `sort:created` | Created order |
| `sort:closed` | Closed order |
| `sort:merged` | Merged order |
| `sort:read` | Read order |
| `sort:archived` | Archived order |
| `sort:bookmark` | Bookmarked order |
| `sort:author` | Author name order |
| `sort:user` | User name/organization name order |
| `sort:repo` | Repository name order |
| `sort:milestone` | Milestone name order |
| `sort:dueon` | Deadline of milestone order |
| `sort:title` | Title order |
| `sort:number` | Issue number order |
| `sort:type` | Issue type(Issue or Pull Request) order |
You can also specify multiple orders and ascending/descending order.
```
sort:"updated desc, author asc"
```
# Browser
This is a reference for Jasper's built-in browser.
## Search within a page
To search within a page, press the magnifying glass icon at the top right of the page. Or you can search by pressing `⌘ + F(Mac)`, `Ctrl + F(Window/Linux)` on your keyboard.
## Open with an external browser
To open the current page in an external browser, press the open icon at the top right of the page. Or you can press `⌘ + O(Mac)` or `Ctrl + O(Windows)` to open the page.
## Show URL
To view the URL of the current page, click on the Issue Information area at the top of the page. Alternatively, you can also display it by pressing `⌘ + L(Mac)` or `Ctrl + L(Window/Linux)` on your keyboard.
## Issue body diff
Displays the differences in the body of the issue, if there have been any updates to the issue body since the last time the issue was viewed.
{% tabs %}
{% tab title="Notice diff" %}
{% endtab %}
{% tab title="Show diff" %}
{% endtab %}
{% endtabs %}
## Unread comment highlights and mini-maps
Highlight any comments that have been added or updated since the issue was last viewed. It will also display those highlighted comments on the map for you to see.
{% tabs %}
{% tab title="コメントのハイライト" %}
{% endtab %}
{% tab title="コメントのミニマップ" %}
{% endtab %}
{% endtabs %}
# Jump Navigation
Jump Navigation reference.
Jump Navigation is a navigation feature that allows you to search for issues within Jasper and navigate to the Stream and Repository. To activate Jump Navigation, press the 🔍 icon in the top left corner, or press `⌘ + K(Mac)` or `Ctrl + K(Window/Linux)`.
{% hint style="info" %}
You can specify the same filters for Jump Navigation searches as Filter Stream. See "[Filter Stream](/reference/filter-stream)" for details.
{% endhint %}
# Keyboard shortcuts
Keyboard shortcuts reference.
## View shortcuts
| action | keyboard shortcuts |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Show Jump Navigation | `⌘ + K`, `Ctrl + K` |
| Show recently viewed issues | `⌘ + E`, `Ctrl + E` |
| Change layout | ⌘ + 1, ⌘ + 2, ⌘ + 3
Ctrl + 1, Ctrl + 2, Ctrl + 3
|
## Stream shortcuts
| action | keyboard shortcuts |
| ------------------------------ | --------------------------- |
| Turn on/off notifications | `⌘ + I`, `Ctrl + I` |
| Go to the next/previous Stream | `D` , `F` |
| Move to the nth Stream | `1` , `2` , `3` , `4` , `5` |
## Issues shortcuts
| action | keyboard shortcuts |
| -------------------------------- | ------------------------ |
| Reload the issues | `.` |
| Go to next/previous issue | `J` , `K` |
| Go to next/previous unread issue | `Shift + J`, `Shift + K` |
| Change to unread/read | `I` |
| Add/delete to your bookmarks | `B` |
| Move to / return to the archive | `E` |
| Show only self author issues | `A` |
| Show only self assigned issues | `N` |
| Show only unread issues | `U` |
| Show only open issues | `O` |
| Show only bookmarked issues | `M` |
## Browser shortcuts
| action | keyboard shortcuts |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Reload the page | `⌘ + R`, `Ctrl + R` |
| Back to previous page | `⌘ + [`, `Ctrl + [` |
| Go to the next page | `⌘ + ]`, `Ctrl + [` |
| Scroll down/up the page. | `Space`, `Shift + Space` |
| Scroll down/up the page significantly | Option + J, Option + K
Alt + J, Alt + K
|
| Search within the page | `⌘ + F`, `Ctrl + F` |
| Open the URL bar | `⌘ + L`, `Ctrl + L` |
| Open the page in an external browser | `⌘ + O`, `Ctrl + O` |
## Customizing keyboard shortcuts (Mac)
{% hint style="warning" %}
Here's a keyboard shortcut on the Mac Window/Linux is not covered in this page.
{% endhint %}
To change the keyboard shortcut to a key of your choice, do the following
* Go to `Keyboard → Shortcuts → Applications` in Mac preferences.
* Add a shortcut key from the `+` button
* Application: `Jasper.app`
* Menu Title: The menu name you want to change the key to(example `Next Issue`)
* Keyboard shortcut: The key you want to set
# FAQ
## Concept
Jasper is more about flexibility than easily, and we aim to tailor the tool's use to a variety of use cases. We've tried to avoid deviating from the core functionality (Stream) of the tool to avoid becoming a "flexible but complex" tool.
This gives us an advantage over other similar tools. However, our emphasis on flexibility means that we are sometimes inferior to similar tools in the following respects
* Hurdles to master
* Requires an understanding of GitHub search
* Overspecified for occasional use.
* Maintenance of user settings
* The user needs to maintain the Stream settings to suit the situation.
* Load on the server when using GHE
* Jasper is a heavy user of the GitHub Search API
That's why we're developing Jasper, balancing flexibility with these shortcomings.
## Smartphone App
Jasper is compatible with Mac/Window/Linux, but it does not support Android/iOS smartphone apps. However, by integrating GitHub Notifications with Jasper, issues viewed from your smartphone's browser can be marked as read in Jasper as well. See "[Smartphone integration](/usecase/advanced#mobile)" for more information.
## Synchronization of Multiple Machines
Jasper does not support multi-machine issue synchronization, although some users have used file synchronization services such as Dropbox to achieve this on their own. But we do not officially support this at this time. If you would like to use this service, try synchronizing the directories you open by going to `Menu → Dev → Open Data Directory`.
## Tabbed Browser
Jasper's built-in browser does not support tabbed browsers. If you wish to view multiple issues at the same time, please use an external browser.
## Issue display speed
When viewing an issue in Jasper's internal browser, it may be slow, but this is due to a slow TTFB (time to first byte) on the GitHub side. I haven't been able to work around this on the Jasper side at the moment.
## Jasper blank screen
If you get a blank screen after starting Jasper, your data may have been corrupted. Follow these steps to delete and initialize the data in Jasper
1. Select `Menu → Dev → Open Data Directory` to view the directory
2. Quit Jasper
3. Delete the `config.json` and `main.db` in the directory we just left.
4. Launch Jasper and re-set up
This will delete the Stream you've created and any issues you've been holding in Jasper, but it will not affect any data on GitHub.
## Polling the GitHub Search API
Jasper's core functionality, Stream, is achieved by polling the [GitHub Search API](https://docs.github.com/en/free-pro-team@latest/rest/reference/search) on a regular basis. Short polling intervals place a heavy load on the GitHub side, while longer intervals result in poor user experience (i.e., issue updates). Jasper strikes a balance between these two by designing the polling as follows
* Instead of polling each Stream, poll the whole Jasper as one poll.
* Therefore, if there are too many Streams, the update interval per Stream will increase.\
To mitigate this problem, see "[Optimizing the update interval](/usecase/advanced#optimize)".
* Automatically extend the polling interval when the GitHub API rate limit is reached
* The rate limit of the GitHub Search API is 10 requests per 60 seconds. The default polling interval is 6 requests per 60 seconds, so the rate limit will never be reached
* GHE(GitHub Enterprise) may have its own rate limit set. Please contact the GHE administrator for more information.
## Supporter Subscriptions
If you want to support the developer ([@h13i32maru](https://twitter.com/h13i32maru)), it would be great if you could make a small subscription through "[Support Subscription](https://h13i32maru.jp/supporter/)".
## Feedback
Please feel free to give us your feedback, and we'd love it if you could write a blog post about Jasper and [#jasperapp](https://twitter.com/hashtag/jasperapp) on Twitter. If you have a bug or feature request, please send it to [jasperapp/jasper](https://github.com/jasperapp/jasper). We'll do our best to address them as much as possible.
## Competitor
Similar to Jasper, tools to manage issue viewing and notification are currently available (2020.09)
| Tool | Active | period |
| ------------------------------------------------------- | ------ | ------------------ |
| [Jasper](https://jasperapp.io/) | ✅ | 2016.06 \~ 2020.07 |
| [Trailer](http://ptsochantaris.github.io/trailer/) | ✅ | 2013.08 \~ 2020.09 |
| [DevHub](https://devhubapp.com/) | ✅ | 2017.05 \~ 2020.08 |
| [Octobox](https://octobox.io/) | ✅ | 2016.12 \~ 2020.09 |
| [GitHawk](http://githawk.com/) | ✅ | 2017.06 \~ 2020.05 |
| [Deck](https://tilfin.github.io/deck/) | | 2016.03 \~ 2019.12 |
| [faao](https://github.com/azu/faao) | | 2017.05 \~ 2019.12 |
| [Cashew](https://github.com/bellebethcooper/cashew) | | 2017.11 \~ 2019.04 |
| [Bee](http://www.neat.io/bee/github-issues-client.html) | | 2013.08 \~ 2018.09 |
| [Gitscout](https://gitscout.com/) | | 2015.11 \~ 2017.05 |
| [Ship](https://www.realartists.com/blog/ship-20.html) | | 2016.01 \~ 2017.01 |
| [DeckHub](https://getdeckhub.com/) | | 2016.02 \~ 2016.04 |
| [BugHub](http://www.bughubapp.com/) | | 2013.04 \~ 2015.11 |
## Articles
Developer articles
* [JasperというGitHub Issue Readerを作りました - blog.h13i32maru.jp](http://blog.h13i32maru.jp/entry/2016/06/08/090000)
* [GitHub用のIssue Reader「Jasper」の開発を振り返ってみる - blog.h13i32maru.jp](http://blog.h13i32maru.jp/entry/2016/12/11/184433)
* [Jasper(GitHub用のIssue Reader)を無料にしました - blog.h13i32maru.jp](https://blog.h13i32maru.jp/entry/2018/07/17/083215)
* [ストレスフリーなGitHubのIssue生活 - techlife.cookpad.com](http://techlife.cookpad.com/entry/2017/03/14/100000)
* [Project of the Week: Jasper - electronjs.o](https://www.electronjs.org/blog/jasper)
User articles
* [GithubのISSUEでなにやらやるなら、Jasperが便利だぞ！の話 - uzulla.hateblo.jp](http://uzulla.hateblo.jp/entry/2016/07/13/021425)
* [GitHub Issue Reader の Jasper を1週間使っての所感 - ohbarye.hatenablog.jp](http://ohbarye.hatenablog.jp/entry/2016/11/19/004719)
* [Check my favorite OSS with Jasper - blog.lorentzca.me](https://blog.lorentzca.me/check-my-favorite-oss-with-jasper/)
* [最近使い始めてよかった３つのMacアプリ - medium.com](https://medium.com/@y_koh/%E6%9C%80%E8%BF%91%E4%BD%BF%E3%81%84%E5%A7%8B%E3%82%81%E3%81%A6%E3%82%88%E3%81%8B%E3%81%A3%E3%81%9F%EF%BC%93%E3%81%A4%E3%81%AEmac%E3%82%A2%E3%83%97%E3%83%AA-2e39bc77c925#.j1hugdgm7)
* [Github Issueを管理するJasperを買った - kechol.hatenablog.jp](http://kechol.hatenablog.jp/entry/jasper-a-github-issue-tracker)
* [GitHub Issue Reader「Jasper」をデザイナーにもオススメしたい - transitkix.hatenablog.jp](http://transitkix.hatenablog.jp/entry/2017/08/10/231124)
* [jasperがよかった - medium.com](https://medium.com/@naomeme/jasper%E3%81%8C%E3%82%88%E3%81%8B%E3%81%A3%E3%81%9F-fb70ebd117c0)
* [Jasper。プロダクトマネージャーがボトルネックとならないための最高のツール - quipper.hatenablog.com](https://quipper.hatenablog.com/entry/2018/06/28/120000)
# Jasperとは
A flexible and powerful issue reader for GitHub
[Jasper](https://jasperapp.io/)はGitHubのissueやpull requestを柔軟な条件で閲覧できるツールです。例えば「自分が作成したpull request」「nodejs/nodeのbugラベルがついたissue」などの条件でissueを閲覧したり更新通知を受け取ることができます。
Jasperではこの機能を**Stream**と呼んでいます。Streamに次のようなクエリを設定することで前述した条件のissueを閲覧することができます。
```
author:defunkt is:pr
```
```
repo:nodejs/node label:bug is:issue
```
## Stream
Streamは[GitHub Search API](https://docs.github.com/en/rest/reference/search)を使って実現されています。GitHub Search APIは非常に強力なクエリを使うことができます。例えば次のようなクエリです。
| 条件 | クエリ |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| defunktが作成したissue | [`author:defunkt is:issue`](https://github.com/search?q=author%3Adefunkt+is%3Aissue) |
| nodejs/nodeリポジトリのpull request | [`repo:nodejs/node is:pr`](https://github.com/search?q=repo%3Anodejs%2Fnode+is%3Apr) |
| nodejs organizationで
bugラベルがついているissue/pull request
| [`org:nodejs label:bug`](https://github.com/search?q=org%3Anodejs+label%3Abug) |
そして、StreamはGitHub Search APIと全く同じクエリを使用することができるため、自分が関心のあるissueを柔軟に閲覧することができます。
{% hint style="info" %}
Streamで使用できるクエリは「[Streamのクエリ](/ja/usecase/query)」や「[Stream](/ja/reference/stream)」を参照してください。
{% endhint %}
## 高い柔軟性
現在、GitHubのissueを閲覧するツールはいくつか存在し、大きく3つのカテゴリにわかれます。
1. issueの閲覧や通知を管理するツール\
[GitHub Notifications](https://github.com/notifications), [DevHub](https://devhubapp.com/), [Trailer](http://ptsochantaris.github.io/trailer/) など
2. チームコラボレーションをするツール\
[GitHub Scheduled reminders](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/managing-scheduled-reminders-for-your-team), [Pull Panda](https://pullpanda.com/) など
3. プロジェクト管理をするツール\
[GitHub Projects](https://docs.github.com/en/github/managing-your-work-on-github/managing-project-boards), [Zen Hub](https://www.zenhub.com/) など
Jasperは1のカテゴリに属するツールです。通常、このカテゴリのツールは[GitHub Notification API](https://docs.github.com/en/rest/reference/activity#notifications)を使っています。しかしJasperは[GitHub Search API](https://docs.github.com/en/rest/reference/search)を使って作られているため他のツールにはない高い柔軟性を実現しています。一方で簡単さについては他のツールより劣る場合があります。そのためJasperは「柔軟性」と「簡単さ」のバランスを考慮しながら開発されています。
{% hint style="info" %}
詳しくは「[コンセプト](/ja/faq#concept)」を参照してください。
{% endhint %}
# クイックスタート
新しくJasperを使い始める場合は「[セットアップ](/ja/quick-start/setup)」「[基本的な使い方](/ja/quick-start/basic-usage)」をお読みください。
すでにJasperを使用しており、新しい環境にデータを移行する場合は「[データ移行](/ja/quick-start/data-migration)」をお読みください。
# セットアップ
Jasperをダウンロードして、GitHubのアクセストークンを設定するだけですぐに使用できます。
## インストール
[jasperapp.io](https://jasperapp.io/) から最新のJasperをダウンロードし、zipファイルを展開してください。Jasperを起動すると、Mac/Windowsでは以下の確認が表示されます。説明に従い起動を完了してください。
{% tabs %}
{% tab title="Mac" %}
{% endtab %}
{% tab title="Windows" %}
{% endtab %}
{% endtabs %}
## アクセストークンの設定
Jasperを起動するとGitHub, GHE(GitHub Enterprise)の選択が表示されます。GHEの場合はホスト名`例 ghe.example.com`を入力してください。
つぎにアクセストークンの入力が必要になります。GitHubとGHEで設定方法が異なります。
{% tabs %}
{% tab title="GitHubの場合" %}
GitHubの場合はOAuthによるアクセストークンの設定を推奨します。画面の指示に従って、OAuth認証を実施してください。
もしくは[Personal access token](https://github.com/settings/tokens)からアクセストークンを作成して使用することもできます。必要なスコープは`repo`, `read:org`, `notifications`, `user`, `read:project` です。
{% endtab %}
{% tab title="GHEの場合" %}
GHEの場合はPersonal access tokenを`https://GHEのホスト/settings/tokens`から作成してください。必要なスコープは`repo`, `read:org`, `notifications`, `user`, `read:project`です。
{% endtab %}
{% endtabs %}
最後に設定内容を確認してOKを押してください。ユーザ名が表示されれば完了です🎉
## 初回読み込み
設定が完了すると、自動的にissueの読み込みが開始されます。この初回の読み込みには数分ほどかかります。Jasperを終了せず、お使いください。
初回読み込み中に「[基本的な使い方](/ja/quick-start/basic-usage)」をお読みいただくことで、Jasperをスムーズに使い始めることができます。
# 基本的な使い方
Jasperの基本的な使い方を紹介します。基本の使い方を覚えるだけで、十分に効率的にissueを閲覧できるようになります。
## Stream
セットアップ後に自動的に次のようなStreamが作成されます。
| Stream | 説明 |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| `Me` | 自分に関係するissue/pull requestを見ることができます。基本的にはこのStreamを見れば見落としはありません。`My Issues`や`My PRs`でフィルターしてみることもできます。 |
| `My Issues` | 自分が作成いたissue |
| `My PRs` | 自分が作成いたpull request |
| `Assigned` | 自分がアサインされているissue/pull request |
| `Review Requested` | 自分がレビュー依頼されたpull request |
また、しばらくすると以下のお知らせが表示されます。手順に従って他のストリームも作成してみてください。
## issue
次の操作はissueの閲覧に特に役立ちます。
| 動作 | 操作方法 |
| -------------- | ----------------------------------------------------------------------------------------- |
| 未読issueだけを表示する | フィルターメニューのFilter by unreadを選択する。
もしくはキーボードの U を押す。
|
| issueを未読に戻す | フローティングメニューの未読アイコンをクリックする。
もしくはキーボードの I を押す。
|
{% tabs %}
{% tab title="フィルターメニュー" %}
{% endtab %}
{% tab title="フローティングメニュー" %}
{% endtab %}
{% endtabs %}
## ブラウザ
前回閲覧時から追加、更新されたコメントはハイライトされて表示されます。
{% hint style="info" %}
さらに詳しい使い方は「[ユースケースごとの使い方](/ja/usecase)」「[リファレンス](/ja/reference)」を参照してください。
{% endhint %}
# データ移行
新しいマシンにJasperのデータを移行することができます。
## 1. 既存のデータを保存
古いマシンでJasperを起動して、`メニュー → Jasper → Export Data`を選択します。
`Open data directory`をクリックして、ディレクトリを表示します。表示されたディレクトリ内にある`config.json`と`main.db`をデスクトップにコピーしてください。これらのデータをGoogle DriveやDropboxなどを使い、新しいマシンに移動してください。
{% hint style="info" %}
Jasperに複数アカウントを登録している場合、`main-123456789.db`のようなファイルもあるので、一緒にコピーしていただく必要があります。
{% endhint %}
## 2. 新しいマシンにデータを移行
新しいマシンでJasperを起動してください。最初の設定画面で`Import Data`を選択します。
`Open data directory`をクリックして、ディレクトリを表示します。このディレクトリに先程移動してきた`config.json`と`main.db`をコピー(上書き)してください。最後に`Restart Jasper`をクリックすれば、データ移行は完了です。
# ユースケース
# Streamのクエリ
Streamには柔軟なクエリを指定することができます。ここではよく使われるクエリを紹介します。
## オープン状態のissue
オープン(クローズやマージされていない)状態のissueを見るStreamを作るには`is:open`を使います。たとえば`nodejs/node`リポジトリのオープンなissueを見るには次のクエリでStreamを作成します。
```
repo:nodejs/node is:open is:issue
```
しかし、Jasperでは`is:open`を使ったStreamを作ることは非推奨です。なぜなら、オープン状態のissueがクローズされたときにJasperではクローズの検知ができないためです。
{% hint style="info" %}
これはJasperがGitHub Search APIをポーリングしていることによる制約です
{% endhint %}
そのため`is:open`を使う場合は通常のStreamではなく、Filter Streamを使うようにしてください。Filter Streamは通常のStreamに対してJasper独自のフィルターをかけることができます。先程の例は次のようになります。
Stream
```
repo:nodejs/node is:issue
```
Filter Stream
```
is:open
```
{% hint style="info" %}
Filter Streamについてはリファレンスの「[Filter Stream](/ja/reference/filter-stream)」を参照してください。
{% endhint %}
{% hint style="info" %}
クローズ状態、マージ状態、ドラフト状態についても同様の制限があります。
{% endhint %}
## Teamメンションされたissue
Teamメンションされたissueを見るには`team:ORGNAME/TEAMNAME`を使います。例えば`@jekyll/owners`がメンションされたissueを見るには次のようなクエリでStreamを作成します。
```
team:@jekyll/owners
```
GitHub Docs: [Search by team mention](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-team-mention)
## ユーザが関係するissue
特定のユーザが関係するissueを見るには`involves:USERNAME`を使います。例えば`defunkt`もしくは`jlord`が関係するissueを見るには次のようなクエリでStreamを作成します。
```
involves:defunkt OR involves:jlord
```
{% hint style="info" %}
`involves:USERNAME`はauthor, assign, mention, comment, review-requestedをまとめて指定することができる便利なクエリです。
{% endhint %}
GitHub Docs: [Search by a user that's involved in an issue or pull request](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-a-user-thats-involved-in-an-issue-or-pull-request)
## リポジトリやOrganizationのissue
特定のリポジトリのissueを見るには`repo:USERNAME/REPOSITORY`を使います。例えば`nodejs/node`もしくは`electron/electron`リポジトリのissueを見るには次のようなクエリでStreamを作成します。
```
repo:nodejs/node OR repo:electron/electron
```
特定のOrganizationのissueを見るには`org:ORGNAME`を使います。例えば`nodejs`や`electron` Organizationのissueを見るには次のようなクエリでStreamを作成します。
```
org:nodejs OR org:electron
```
GitHub Docs: [Search within a user's or organization's repositories](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-within-a-users-or-organizations-repositories)
## マイルストーンやラベルがついたissue
特定のマイルストーンが付いたissueを見るには`milestone:MILESTONE_NAME`を使います。例えば`nodejs/node`リポジトリで`13.0.0`もしくは`14.0.0`のマイルストーンがついたissueを見るには次のようなクエリでStreamを作成します。
```
repo:nodejs/node ( milestone:13.0.0 OR milestone:14.0.0 )
```
特定のラベルが付いたissueを見るには`label:LABEL_NAME`を使います。例えば`nodejs/node`リポジトリで`build`**と**`zlib`のラベルが付いたissueを見るには次のようなクエリでStreamを作成します。
```
repo:nodejs/node label:build label:zlib
```
{% hint style="info" %}
複数のラベルを指定するとand条件となります。
{% endhint %}
{% hint style="info" %}
スペースを含むマイルストーンやラベルの場合は`milestone:"foo bar"`のように指定してください。
{% endhint %}
GitHub Docs: [Search by milestone](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-milestone), [Search by label](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests#search-by-label)
## キーワードが含まれるissue
特定のキーワードが含まれるissueを見るにはKEYWORDを使います。例えばoctocatとgithubが含まれるissueを見るには次のようなクリエでStreamを作成します。
{% tabs %}
{% tab title="AND条件" %}
```
octocat github
```
{% endtab %}
{% tab title="OR条件" %}
```
octocat OR github
```
{% endtab %}
{% tab title="NOT条件" %}
```
octocat NOT github
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
日本後などのマルチバイト文字やスペースを含むキーワードは`"foo bar"`のように指定してください。
{% endhint %}
GitHub Docs: [Limitations on query length](https://docs.github.com/en/github/searching-for-information-on-github/troubleshooting-search-queries#limitations-on-query-length), [Exclude certain results](https://docs.github.com/en/github/searching-for-information-on-github/understanding-the-search-syntax#exclude-certain-results)
## 除外指定
特定のリポジトリやラベルを含まないように指定するには`-QUALIFIER`を使います。例えば`nodejs` organizatonで`nodejs/node`リポジトリと`bug`ラベルを含まいないissueを見るには次のようなクエリでStreamを作成します。
```
org:nodejs -repo:nodejs/node -label:bug
```
GitHub Docs: [Exclude certain results](https://docs.github.com/en/github/searching-for-information-on-github/understanding-the-search-syntax#exclude-certain-results)
# issueの閲覧
効率的にissueを閲覧できるようにJasperには様々な機能があります。ここではよく使われる機能をいくつか紹介します。
## 未読issueを表示
未読issueだけを素早く表示するにはissueのフィルター機能を使います。issue一覧の上部にあるフィルターから`Filter by unread`を選択してください。もしくはキーボードの `U` を押すことで未読issueだけを表示することもできます。
## あとで読む
あとで読む場合、Jasperでは2つの方法があります。
1つ目はissueを未読に戻す方法です。issueのフローティングメニューから`Mark as Unread`を選択します。もしくは選択状態のissueに対してキーボードの `I` を押して未読に戻すこともできます。
2つ目の方法はブックマークに登録する方法です。issueのフローティングメニューから`Add to Bookmark`を選択します。もしくは選択状態のissueに対してキーボードの `B` を押してブックマークに登録することもできます。
{% tabs %}
{% tab title="未読に戻す" %}
{% endtab %}
{% tab title="ブックマークする" %}
{% endtab %}
{% endtabs %}
## 不要なissueを除外
今後閲覧する必要がないissueを除外する場合、アーカイブ機能を使用できます。アーカイブするにはフローティングメニューから`Move to Archive`を選択します。もしくは選択状態のissueに対してキーボードの `E` を押してアーカイブすることもできます。
## 未読コメントを確認
Jasperの内部ブラウザでissueを閲覧すると、前回閲覧時から追加・更新されたコメントがハイライトされます。またissueの左側に追加・更新されたコメントのミニマップが表示されます。このコメントのハイライトとミニマップを使って未読のコメントを素早く確認できます。
{% tabs %}
{% tab title="コメントのハイライト" %}
{% endtab %}
{% tab title="コメントのミニマップ" %}
{% endtab %}
{% endtabs %}
また、issueの本文に関しては更新があった場合は差分が表示されます。
{% tabs %}
{% tab title="差分のお知らせ" %}
{% endtab %}
{% tab title="差分の表示" %}
{% endtab %}
{% endtabs %}
# issueの検索
Streamや全体からissueを検索することができます。
## Streamから検索
任意のStreamからissueを検索するには`Filter`機能を使います。Filterを使うにはissueリストの上部にあるフィルターアイコンをクリックしてください。
{% hint style="info" %}
Filterでの検索にはFilter Streamと同じフィルターが使用できます。詳しくはリファレンスの「[Filter Stream](/ja/reference/filter-stream)」を参照してください。
{% endhint %}
## 全体から検索
Jasperが保持している全issueの中から検索を行うには`Jump Navigation`機能を使います。Jump Navigationは左上の🔍アイコンから開始します。もしくは`⌘ + K (Mac)`, `Ctrl + K (Window/Linux)`を押すことでも開始できます。
{% hint style="info" %}
Jump Navigationでの検索にはFilter Streamと同じフィルターが使用できます。詳しくはリファレンスの「[Filter Stream](/ja/reference/filter-stream)」を参照してください。
{% endhint %}
# 見た目と通知
Jasperを使いやすくするために見た目や通知の設定方法を紹介します。
## Streamの色や通知を設定する
Streamは詳細設定から色とアイコンを設定できます。これによりグルーピングをしたり、重要なStreamを目立つようにできます。
また、通知はStreamごとにオン/オフを設定することができます。通知されるほどではないStreamについては通知をオフにすることで重要な通知を見逃さなくなります。通知はPreferences画面からまとめて設定することもできます。
{% tabs %}
{% tab title="Streamの詳細" %}
{% endtab %}
{% tab title="まとめて設定" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
アイコンは[Material Design Icons](https://materialdesignicons.com/)に登録されている全種類のアイコンを使用できます。
{% endhint %}
## 全体の通知設定
集中してissueやpull requestを閲覧したい場合、全体の通知をオフにすることもできます。通知をオン/オフの切り替えは左上の🔔アイコンからできます。もしくは`⌘ + I`を押すことでもできます。
## 表示レイアウトを変える
画面が小さい場合やpull requestのコードレビューをする場合、issueの表示領域を大きくすることができます。表示領域を大きくするには右上のレイアウトアイコンから切り替えることができます。もしくは`⌘ + 1`, `⌘ + 2`, `⌘ + 3`を押すことでも切り替えることができます。
{% tabs %}
{% tab title="レイアウトアイコン" %}
{% endtab %}
{% tab title="3レイアウト(通常時)" %}
{% endtab %}
{% tab title="2レイアウト" %}
{% endtab %}
{% tab title="1レイアウト" %}
{% endtab %}
{% endtabs %}
## Streamを非表示にする
不要なStreamを非表示にすることができます。例えば`Inbox`や`Archive`を使わない場合は、非表示にすることでJasperを見やすくすることができます。
# キーボード操作
Jasperには様々なキーボードショートカットがあります。ここではよく使われるキーボードショートカットを紹介します。
## よく使われるキーボードショートカット
| 動作 | キーボードショートカット |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Jump Navigationを表示 | `⌘ + K`, `Ctrl + K` |
| 通知のオン/オフ | `⌘ + I`, `Ctrl + I` |
| レイアウトを変更 | ⌘ + 1, ⌘ + 2, ⌘ + 3
Ctrl + 1, Ctrl + 2, Ctrl + 3
|
| 未読issueを表示 | `U` |
| 次/前のStreamを表示 | `D` , `F` |
| 次/前のissueを表示 | `J` , `K` |
| ブラウザのスクロール | `Space`, `Shift + Space` |
{% hint style="info" %}
全てのキーボードショートカットを見るにはリファレンスの「[キーボードショートカット](/ja/reference/keyboard-shortcut)」を参照してください。
{% endhint %}
{% hint style="info" %}
キーボードショートカットをカスタマイズする場合は「[キーボードショートカットをカスタマイズする(Mac)](/ja/reference/keyboard-shortcut#customize)」を参照してください。
{% endhint %}
# 高度な設定
GitHubとの高度な連携や、Streamの更新間隔を最適化する方法を紹介します。
## スマートフォンと連携
スマートフォンや通常のブラウザで閲覧したissueを、Jasperでも既読にするためにはGitHub Notification Syncを有効にします。
この設定を有効にすると定期的(通常は60秒間隔)に[GitHub Notification](https://github.com/notifications)からJasper側に反映させます。
{% hint style="warning" %}
JasperからGitHub Notificationへの反映は「issueを閲覧して既読にした」場合のみ行われます。次の操作はGitHub Notificationへは反映されません。
* Jasperで未読にしたissue
* Jasperでメニューやキーボードショートカットにより既読にしたissue
{% endhint %}
## GitHub Projectsと連携
特定のGithub Projectsに関連するissueを見るにはProject Streamを作成します。
{% tabs %}
{% tab title="Project Streamの作成" %}
{% endtab %}
{% tab title="Project Streamの表示" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
`project:REPOSITORY/PROJECT_BOARD`クエリを使い、通常のStreamを作成しGitHub Projects に関連するissueを見ることはできます。しかしProject Streamを使うことでProject Board(カンバン)との連携が可能になるので、Project Streamを使うことをおすすめします。
{% endhint %}
## GitHub Teamと連携
自分が所属するGitHub Teamへメンションされたissueを見るにはTeam Streamを使います。Team Streamは設定画面から有効にします。
{% tabs %}
{% tab title="Team Streamの有効にする" %}
{% endtab %}
{% tab title="Team Stream" %}
{% endtab %}
{% tab title="Team Streamの内容" %}
自分が所属するTeamからクエリが自動的に作成されます。
{% endtab %}
{% endtabs %}
## GitHub Watchingと連携する
自分がGitHub上でwatchしたリポジトリのissueを見るにはWatching Streamを使います。Watching Streamは設定画面から有効にします。
{% tabs %}
{% tab title="Watching Streamの有効にする" %}
{% endtab %}
{% tab title="Watching Stream" %}
{% endtab %}
{% tab title="Watching Streamの内容" %}
自分がwatchするリポジトリからクエリが自動的に作成されます。
{% endtab %}
{% endtabs %}
## 任意のissueを登録する
リポジトリやorganizationではなく、issue単独でStreamにしたい場合はSubscription Streamを使います。Subscription Streamは設定画面から有効にします。
{% tabs %}
{% tab title="Subscription Streamを有効にする" %}
{% endtab %}
{% tab title="Subscription Stream" %}
{% endtab %}
{% tab title="issueを登録する" %}
Subscription Streamを右クリックして、メニューからissueのURLを登録します。
{% endtab %}
{% endtabs %}
## 更新間隔を最適化する
Jasperは通常10秒ごとにissueを検索して更新を取得しています。この更新間隔はStreamごとではなく、Jasper全体の更新間隔です。つまり、Streamをたくさん作れば作るほど、Stream1個あたりの更新は遅くなります。例えばStreamを3つ作っていた場合、1つのStreamが更新されるのは30秒ごとになります。
{% hint style="info" %}
このような動作になっているのは、Streamが増えてもGitHub側に負荷をかけないようにするためです。
{% endhint %}
このため、たくさんStreamを作ると更新が遅くなってしまいます。そこで、通常のStreamを少なくしてFilter Streamを積極的に使うことで、更新が遅くならないようにします。
{% hint style="info" %}
Filter StreamはGitHubの検索を行わず、ローカルのissueをフィルターするため更新間隔に影響を与えません。Filter Streamについての詳細は「[Filter Stream](/ja/reference/filter-stream)」を参照してください。
{% endhint %}
例えば次のような2つのStreamを作るのではなく、1つのStreamと2つのFilter Streamを作ります。こうすることで前者では1つのStreamあたり20秒間隔の更新だったものが、後者では1つのStreamあたり10秒間隔になります。
{% tabs %}
{% tab title="2つのStream" %}
```
org:nodejs
```
```
org:electron
```
{% endtab %}
{% tab title="1つのStreamと2つのFilter Stream" %}
```
org:nodejs org:electron
```
```
org:nodejs
```
```
org:electron
```
{% endtab %}
{% endtabs %}
JasperではこのようにFilter Streamを積極的に利用することを推奨しています。
# リファレンス
# Stream
Streamに使用できるクエリのリファレンスです。
Streamは`Add Stream`メニューから追加します。
{% tabs %}
{% tab title="Streamの追加" %}
{% endtab %}
{% tab title="Streamの設定" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Streamに使用できるクエリはGitHub Searchのクエリと完全に互換性があります。GitHub Searchの全クエリとシンタックスについては「[Searching issues and pull requests - github.com](https://docs.github.com/en/github/searching-for-information-on-github/searching-issues-and-pull-requests)」と「[Understanding the search syntax - github.com](https://docs.github.com/en/github/searching-for-information-on-github/understanding-the-search-syntax)」を参照してください。
{% endhint %}
## issueの状態
| クエリ | 説明 |
| ------------------------------------------------------------------- | ----------------------------- |
| `is:issue`, `is:pr` | issueのみ、pull requestのみ |
| is:open, is:closed
※非推奨
| オープンされているissue、クローズされているissue |
| is:merged, is:unmerged
※非推奨
| マージされているissue、マージされていないissue |
| draft:true, draft:false
※非推奨
| ドラフトのissue、ドラフトではないissue |
{% hint style="warning" %}
オープン状態、マージ状態、ドラフト状態のクエリは非推奨です。これらのクエリを使用する場合はFilter Streamをお使いください。詳しくは[こちら](/ja/usecase/query#open-issue)を参照してください。
{% endhint %}
## ユーザやチーム
| クエリ | 説明 |
| -------------------- | ----------------- |
| `involves:defunkt` | ユーザが関係するissue |
| `author:defunkt` | ユーザが作成したissue |
| `assignee:defunkt` | ユーザがアサインされたissue |
| `mentions:defunkt` | ユーザがメンションされたissue |
| `commenter:defunkt` | ユーザがコメントしたissue |
| `team:github/owners` | チームがメンションされたissue |
{% hint style="info" %}
同じ種類のクエリを複数指定するとOR条件になります。例えば、`involves:defunkt involves:jlord` は`defunkt`もしくは`jlord`が関係するissueです。
{% endhint %}
{% hint style="info" %}
involvesはauthor, assignee, mentions, commenter, review-requestedをまとめて指定したものと同様になります。
{% endhint %}
## Pull requestレビュー
| クエリ | 説明 |
| --------------------------------------------- | ----------------------------------------------------------------------- |
| `review-requested:defunkt` | ユーザにレビューリクエストされたpull request |
| `team-review-requested:github/owners` | チームにレビューリクエストされたpull request |
| `reviewed-by:defunkt` | ユーザがレビューしたpull request |
| `review:approved`, `review:changes_requested` | approvedされたpull request,
changes requestedされたpull request
|
{% hint style="info" %}
同じ種類のクエリを複数指定するとOR条件になります。例えば、`review-requested:defunkt review-requested:jlord`は`defunkt`もしくは`jlord`がレビューリクエストされたpull requestです。
{% endhint %}
## リポジトリやOrganization
| クエリ | 説明 |
| ------------------ | ------------------ |
| `repo:nodejs/node` | リポジトリのissue |
| `org:nodejs` | Organizationのissue |
| `user:defunkt` | ユーザ下のissue |
{% hint style="info" %}
同じ種類のクエリを複数指定するとOR条件になります。例えば、`repo:nodejs/node repo:electron/electron`は`nodejs/node`もしくは`electron/electron`のissueです。
{% endhint %}
## ラベルやマイルストーンなど
| クエリ | 説明 |
| --------------------------- | ------------------------ |
| `label:bug` | ラベルがついたissue |
| `milestone:v1.0.0` | マイルストーンがついたissue |
| `project:github/57` | Organizationプロジェクトのissue |
| `project:github/linguist/1` | リポジトリプロジェクトのissue |
{% hint style="info" %}
同じ種類のクエリを複数指定するとOR条件になります。例えば、`milestone:v1.0.0 milestone:v2.0.0`は`v1.0.0`もしくは`v2.0.0`のissueです。\
ただし、ラベルについてはAND条件となります。
{% endhint %}
{% hint style="info" %}
スペースを含むラベルやマイルストーンの場合は`label:"foo bar"`のようにダブルクオーテーションで囲んでください。
{% endhint %}
## 任意のキーワード
| クエリ | 説明 |
| -------------------- | ---------------------- |
| `github octocat` | キーワード(AND条件)が含まれるissue |
| `github OR octocat` | キーワード(OR条件)が含まれるissue |
| `github NOT octocat` | キーワード(NOT条件)が含まれるissue |
{% hint style="info" %}
スペースを含む場合は`"hello world"`のようにダブルクオーテーションで囲んでください。
{% endhint %}
{% hint style="info" %}
AND, OR, NOTについては5つまでしか含まれることはできません。詳しくは「[Limitations on query length - github.com](https://docs.github.com/en/github/searching-for-information-on-github/troubleshooting-search-queries#limitations-on-query-length)」を参照してください。
{% endhint %}
## 除外・未設定
| クエリ | 説明 |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| -label:bug, -milestone:v0.0.1,
-repo:nodejs/node -involves:defunk...
| 指定した条件が含まれないissue |
| no:label, no:milestone,
no:assignee, no:project
| ラベル、マイルストーン、アサイン、
プロジェクトが設定されていないissue
|
# Filter Stream
Filter Streamで使用できるフィルターのリファレンスです。
Filter StreamはStreamのissueをフィルターして表示します。
Filter StreamはStreamのメニューにある`Add Filter Stream`から追加します。もしくはトップレベルに作成する場合は`Add Filter Stream top-level`から追加します。また、一時的にFilterを適用することもできます。
{% tabs %}
{% tab title="Filter Streamの追加" %}
{% endtab %}
{% tab title="Filter Streamの設定" %}
{% endtab %}
{% tab title="Top Levelへの追加" %}
{% endtab %}
{% tab title="一時的" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Filter Streamで使用できるフィルターはStreamとほとんど同じ条件を指定できます。ただし、少し異なるものもあるので注意してください。
{% endhint %}
## issueの状態
| フィルター | 説明 |
| ------------------------------ | ------------------------------------------------ |
| `is:issue`, `is:pr` | issueのみ、pull requestのみ |
| `is:open`, `is:closed` | オープンされているissue、クローズされているissue |
| `is:merged`, `is:unmerged` | マージされているissue、マージされていないissue |
| `draft:true`, `draft:false` | ドラフトのissue、ドラフトではないissue |
| `is:read`, `is:unread` | 既読のissue、未読のissue |
| `is:bookmark`, `is:unbookmark` | ブックマークされたissue、
ブックマークされていないissue
|
| `is:archived`, `is:unarchived` | アーカイブされたissue、
アーカイブされていないissue
|
| `is:private`, `is:unprivate` | プライベートリポジトリのissue、
パブリックリポジトリのissue
|
## ユーザやチーム
| フィルター | 説明 |
| -------------------- | ----------------- |
| `involves:defunkt` | ユーザが関係するissue |
| `author:defunkt` | ユーザが作成したissue |
| `assignee:defunkt` | ユーザがアサインされたissue |
| `mentions:defunkt` | ユーザがメンションされたissue |
| `team:github/owners` | チームがメンションされたissue |
{% hint style="info" %}
同じ種類のフィルターを複数指定するとOR条件になります。例えば、`involves:defunkt involves:jlord`は`defunkt`もしくは`jlord`が関係するissueです。
{% endhint %}
{% hint style="info" %}
`involves`は`author`, `assignee`, `mentions`,`commenter`, `review-requested`をまとめて指定したものと同様になります。
{% endhint %}
## Pull requestレビュー
| フィルター | 説明 |
| -------------------------- | -------------------------------- |
| `review-requested:defunkt` | ユーザ/チームがレビューリクエストされたpull request |
| `reviewed-by:defunkt` | ユーザがレビューしたpull request |
{% hint style="info" %}
同じ種類のクエリを複数指定するとOR条件になります。例えば、`review-requested:defunkt review-requested:jlord`は`defunkt`もしくは`jlord`がレビューリクエストされたpull requestです。
{% endhint %}
## リポジトリやOrganization
| フィルター | 説明 |
| ------------------ | ------------------ |
| `repo:nodejs/node` | リポジトリのissue |
| `org:nodejs` | Organizationのissue |
| `user:defunkt` | ユーザ下のissue |
{% hint style="info" %}
同じ種類のクエリを複数指定するとOR条件になります。例えば、`repo:nodejs/node repo:electron/electron`は`nodejs/node`もしくは`electron/electron`のissueです。
{% endhint %}
## ラベルやマイルストーンなど
| フィルター | 説明 |
| -------------------------------------- | ----------------------------------------- |
| `label:bug`, `label:bug-%` | ラベルがついたissue
%は任意の文字列にマッチ
|
| `milestone:v1.0.0`, `milestone:v2.0.%` | マイルストーンがついたissue
%は任意の文字列いマッチ
|
| `title:テスト`, `title:%テスト%` | 指定されたタイトルがついたissue
%は任意の文字列いマッチ
|
| `project-name:hello-pj` | プロジェクトに紐付いたissue |
| `project-column:now-doing` | プロジェクトカラムに紐付いたissue |
| `number:123` | 特定のissue番号 |
ラベルには以下のように動的な日付を指定することもできます。
| フィルター | 説明（今日が2022-08-16だとする） |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `label:release_@current_date` | `@current_date`が現在の日付に置き換えられます。つまりフィルターとしては`label:release_2022%08%16`が実行されます。 |
| `label:release_@prev_date` | `@prev_date`が昨日の日付に置き換えられます。つまりフィルターとしては`label:release_2022%08%15`が実行されます。 |
| `label:release_@next_date` | `@next_date`が明日の日付に置き換えられます。つまりフィルターとしては`label:release_2022%08%17`が実行されます。 |
| `label:release_@current_date+1`, `label:release_@current_date-1` | `@current_date`に続けて、`+1`や`-1`を指定すると、現在の日付から相対的な日付に置き換えられます。つまりフィルターはとしては`label:release_2022%08%17`や`label:release_2022%08%15`が実行されます。 |
{% hint style="info" %}
同じ種類のクエリを複数指定するとOR条件になります。例えば、`milestone:v1.0.0 milestone:v2.0.0`は`v1.0.0`もしくは`v2.0.0`のマイルストーンがついたissueです。ただし、ラベルについてはAND条件となります。
{% endhint %}
{% hint style="info" %}
スペースを含むラベルやマイルストーンの場合は`label:"`hello `world"`のようにダブルクオーテーションで囲んでください。
{% endhint %}
## GitHub プロジェクト
| フィルター | 説明 |
| ----------------------------------------- | --------------------------------- |
| `project-field:status/ToDo` | statusフィールドがToDoになっているissue |
| `project-field:sprint/@current_iteration` | sprintフィールドが現在のイテレーションになっているissue |
| `project-field:foo/bar` | fooフィールドがbarになっているissue |
以下はclassicプロジェクト用のフィルターです。
| フィルター | 説明 |
| -------------------------------------------- | ------------------- |
| `project-name:hello-pj` (classic project) | プロジェクトに紐付いたissue |
| `project-column:now-doing` (classic project) | プロジェクトカラムに紐付いたissue |
## 任意のキーワード
| フィルター | 説明 |
| ---------------- | ---------------------- |
| `github octocat` | キーワード(AND条件)が含まれるissue |
{% hint style="info" %}
スペースを含む場合は`"hello world"`のようにダブルクオーテーションで囲んでください。
{% endhint %}
{% hint style="info" %}
キーワードはissue本文, author, assignee, label, milestone, repository, org, involves, review-requested, review, project-name, project-columnsを対象とします。
{% endhint %}
{% hint style="warning" %}
OR, NOTには対応していません。
{% endhint %}
## 除外・欠如
| フィルター | 説明 |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `-label:bug`, `-milestone:v0.0.1`, `-repo:nodejs/node` `-involves:defunk`... | 指定した条件が含まれないissue |
| `no:label`, `no:milestone`, `no:assignee`, `no:project`, `no:dueon` | ラベル、マイルストーン、アサイン、 プロジェクト、締切が設定されていないissue |
| have:label, have:milestone, have:assignee, have:project,
have:dueon
| ラベル、マイルストーン、アサイン、 プロジェクト、締切が設定されているissue |
# Project Stream
Project Streamのリファレンスです。
Project Streamには「プロジェクトの提案」からあなたが関わったGitHubプロジェクトを指定することができます。もしくはGitHub ProjectのURLを手動で指定することもできます。
{% tabs %}
{% tab title="Project Streamの追加" %}
{% endtab %}
{% tab title="Project Streamの設定" %}
{% endtab %}
{% endtabs %}
Project Streamを選択すると、Project Boardが自動的に表示されます。Project Board上のissueはJasper内の未読・既読が反映されて表示されます。
# Library Stream
Library Streamのリファレンスです。
Library StreamとはJasper内のissueを横断的に整理したものです。Library Streamを使用する場合は`メニュー → Preferences → Streams`から有効にしてください。
| Library Stream | 内容 |
| -------------- | ------------------------- |
| `Inbox` | アーカイブされていない全てのissue |
| `Open` | アーカイブされていないオープン状態のissue |
| `Unread` | アーカイブされていない未読issue |
| `Bookmark` | アーカイブされていないブックマークされたissue |
| `Archived` | アーカイブされたissue |
デフォルトでは`Inbox`, `Bookmark`, `Archived`が有効になっています。
# System Stream
System Streamのリファレンスです。
System Streamとは動的にクエリを生成するシステム組み込みのストリームです。System Streamを使用する場合は`メニュー → Preferences → Streams`から有効にしてください。
| System Stream | 説明 |
| -------------------- | -------------------------------- |
| `Team Stream` | 自身がGitHub上で所属するチームがメンションされたissue |
| `Watching Stream` | 自身がGitHub上でwatchしているリポジトリのissue |
| `Subscription Issue` | 個別に指定されたissue |
`Team Stream`は自身がGitHub上で所属するチームを取得して、そのチームがメンションされたissueを扱うことができます。新しくチームに所属した場合、自動的にチームが追加されます。
`Watching Stream`は自身がGitHub上でwatchしたリポジトリを取得して、そのリポジトリのissueを扱うことができます。新しくリポジトリをwatchした場合、自動的にリポジトリが追加されます。
`Subscription Stream`は個別に指定されたissueを扱うことができます。Subscription StreamのメニューからissueのURLを登録してください。
# 並び順
issueの並び順についてのリファレンスです。
通常、issueは更新順で表示されています。issue一覧の上部にある並び順アイコンから並び順を変更することができます。また、Filter StreamやFilterに`sort:ORDER`を指定することで並び順を変更することもできます。
{% tabs %}
{% tab title="並び順の変更" %}
{% endtab %}
{% tab title="Filterにsort:ORDERを指定" %}
{% endtab %}
{% endtabs %}
`sort:ORDER`には次の値を指定できます。
| sort | 説明 |
| ---------------- | ------------------------------- |
| `sort:updated` | 更新順 |
| `sort:created` | 作成順 |
| `sort:closed` | クローズ順 |
| `sort:merged` | マージ順 |
| `sort:read` | 閲覧順 |
| `sort:archived` | アーカイブされた順 |
| `sort:bookmark` | ブックマークされた順 |
| `sort:author` | 作者名順 |
| `sort:user` | ユーザ名、organization名順 |
| `sort:repo` | リポジトリ名順 |
| `sort:milestone` | マイルストーン名順 |
| `sort:dueon` | マイルストーンに設定されている締切日順 |
| `sort:title` | タイトル順 |
| `sort:number` | issueの番号順 |
| `sort:type` | issueの種類（Issue or Pull Request） |
複数の並び順、昇順/降順を指定することもできます。
```
sort:"updated desc, author asc"
```
# ブラウザ
Jasperの組み込みブラウザについてのリファレンスです。
## ページ内検索
ページ内の検索を行うにはページ右上の虫眼鏡アイコンを押してください。もしくはキーボードの`⌘ + F(Mac)`, `Ctrl + F(Window/Linux)`を押すことで検索することもできます。
## 外部ブラウザで開く
現在のページを外部ブラウザで開くにはページ右上の開くアイコンを押してください。もしくはキーボードの`⌘ + O(Mac)`, `Ctrl + O(Windows)`を押すことでも開くことができます。
## URLを表示
現在のページのURLを表示するにはページ上部のissue情報エリアをクリックしてください。もしくはキーボードの`⌘ + L(Mac)`, `Ctrl + L(Window/Linux)`を押すことでも表示することができます。
## issue本文の差分表示
issueを前回閲覧した時からissue本文に更新があれば、その差分を表示します。
{% tabs %}
{% tab title="差分のお知らせ" %}
{% endtab %}
{% tab title="差分の表示" %}
{% endtab %}
{% endtabs %}
## 未読コメントのハイライト・ミニマップ
issueを前回閲覧した時からコメントの追加・更新があれば、そのコメントをハイライト表示します。また、それらのハイライトされたコメントを見にマップ上に表示します。
{% tabs %}
{% tab title="コメントのハイライト" %}
{% endtab %}
{% tab title="コメントのミニマップ" %}
{% endtab %}
{% endtabs %}
# ジャンプナビゲーション
Jump Navigationのリファレンスです。
Jump NavigationはJasper内のissueを検索したり、Streamやリポジトリに移動するナビゲーション機能です。Jump Navigationを起動するには左上部にある🔍アイコン、もしくは`⌘ + K(Mac)`、`Ctrl + K(Window/Linux)` を押してください。
{% hint style="info" %}
Jump Navigationの検索にはFilter Streamと同じフィルターを指定することができます。詳しくは「[Filter Stream](/ja/reference/filter-stream)」を参照してください。
{% endhint %}
# キーボードショートカット
キーボードショートカットのリファレンスです。
## Viewのショートカット
| 動作 | キーボードショートカット |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Jump Navigationの表示 | `⌘ + K`, `Ctrl + K` |
| 最近閲覧したissueを表示 | `⌘ + E`, `Ctrl + E` |
| レイアウトを変更 | ⌘ + 1, ⌘ + 2, ⌘ + 3
Ctrl + 1, Ctrl + 2, Ctrl + 3
|
## Streamのショートカット
| 動作 | キーボードショートカット |
| ------------- | --------------------------- |
| 通知のオン/オフ | `⌘ + I`, `Ctrl + I` |
| 次/前のStreamに移動 | `D` , `F` |
| n番目のStreamに移動 | `1` , `2` , `3` , `4` , `5` |
## issueのショートカット
| 動作 | キーボードショートカット |
| --------------------- | ------------------------ |
| issueリストをリロード | `.` |
| 次/前のissueに移動 | `J` , `K` |
| 次/前の未読issueに移動 | `Shift + J`, `Shift + K` |
| 未読/既読に変更 | `I` |
| ブックマークへの追加/削除 | `B` |
| アーカイブへの移動/復帰 | `E` |
| 自身が作者のissueのみ表示 | `A` |
| 自身がアサインされているissueのみ表示 | `N` |
| 未読のissueのみ表示 | `U` |
| オープン状態のissueのみ表示 | `O` |
| ブックマークしているissueのみ表示 | `M` |
## ブラウザのショートカット
| 動作 | キーボードショートカット |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| ページを再読み込み | `⌘ + R`, `Ctrl + R` |
| ページを前に戻る | `⌘ + [`, `Ctrl + [` |
| ページを次に進む | `⌘ + ]`, `Ctrl + [` |
| ページを下/上にスクロール | `Space`, `Shift + Space` |
| ページを大きく下/上にスクロール | Option + J, Option + K
Alt + J, Alt + K
|
| ページ内を検索 | `⌘ + F`, `Ctrl + F` |
| URLバーを開く | `⌘ + L`, `Ctrl + L` |
| ページを外部ブラウザで開く | `⌘ + O`, `Ctrl + O` |
## キーボードショートカットをカスタマイズする(Mac)
{% hint style="warning" %}
ここではMacでのキーボードショートカット
のカスタマイズ方法を紹介します。Window/Linuxについては対象外です。
{% endhint %}
キーボードショートカットを任意のキーに変更するには次のように行います
* Macの設定から「`キーボード` → `ショートカット` → `アプリケーション`」を表示
* `+` ボタンかららショートカットキーを追加します
* アプリケーション: `Jasper.app`
* メニュータイトル: キーを変更したいメニュー名(例 `Next Issue`)
* キーボードショートカット: 設定したいキー
# FAQ
## コンセプト
Jasperは「簡単さ」よりも「柔軟性」を重視し、様々なユースケースに合わせた使い方ができることを目指しています。そして、「柔軟ではあるが複雑」なツールにならないようにコア機能(Stream)から外れた機能はなるべく作らないようにしています。
これにより、類似のツールにはない強みを実現しています。しかし、「柔軟性」を重視したことにより、次の点においては類似のツールに劣る場合があります。
* 使いこなすためのハードル
* GitHub検索への理解を必要とする
* たまに使うにはオーバースペック
* ユーザ設定のメンテナンス
* 状況に合わせた設定をユーザがメンテナンスしていく必要がある
* GHE利用時のサーバ側への負荷
* GitHub Search APIをヘビーに使用している
そのため、柔軟性とこれらの欠点のバランスを考えながらJasperを開発しています。
## スマートフォンアプリ
JasperはMac/Window/Linuxに対応していますが、Android/iOSのスマートフォンアプリには対応していません。しかし、GitHub NotificationsとJasperを連携させることで、スマートフォンのブラウザから閲覧したissueをJasperでも既読にすることができます。詳しくは「[スマートフォンと連携](/ja/usecase/advanced#mobile)」を参照してください。
## 複数マシンの同期
Jasperは複数マシンでのissue同期には対応していません。Dropboxなどのファイル同期サービスを使って独自に実現しているユーザはいますが、現在は公式サポートしておりません。もしご利用になりたい場合は`メニュー → Dev → Open Data Directory`から開くディレクトリを同期してお試しください。
## タブブラウザ
Jasperの組み込みブラウザはタブブラウザには非対応です。複数のissueを同時に閲覧する場合は外部ブラウザをご利用ください。
## issueの表示速度
Jasperの内部ブラウザでissueを表示したときに、表示速度が遅い場合があります。しかしこれはGitHub側のTTFB(time to first byte)が遅いためです。Jasper側で改善する目処は今の所たっていません。
## Jasperが表示されなくなった
Jasperを起動しても真っ白な画面になってしまう場合、データが破損した可能性があります。次の手順でJasperのデータを削除して初期化ください。
1. `メニュー → Dev → Open Data Directory`を選択してディレクトリを表示
2. Jasperを終了
3. 先程のディレクトリ内にある`config.json`, `main.db`を削除
4. Jasperを起動して再セットアップ
この操作を行うと作成済みのStreamやJasper内に保持していたissueは削除されますが、GitHub側のデータには一切影響ありません。
## GitHub Search APIのポーリング
Jasperのコア機能であるStreamは[GitHub Search API](https://docs.github.com/en/rest/reference/search)を定期的にポーリングすることで実現しています。ポーリングは短い間隔にするとGitHub側に負荷がかかり、長い間隔にするとユーザ側の使い勝手(issueの更新)が悪くなります。そこで、Jasperでは以下のようなポーリング設計とすることで、両者のバランスをとっています。
* Streamごとにポーリングするのではなく、Jasper全体で1つのポーリングとする
* このため、Streamが増えすぎると1つのStreamあたりの更新間隔が伸びる。\
この問題を緩和するには「[更新間隔を最適化する](/ja/usecase/advanced#optimize)」を参照してください。
* GitHub APIのrate limitに達した場合、ポーリング間隔を自動的に伸ばす
* GitHub Search APIのrate limitは60秒間に10リクエストです。デフォルトのポーリング間隔では60秒間に6リクエストであるため、rate limitに達することはありません
* GHE(GitHub Enterprise)ではrate limitが独自に設定されている場合があります。詳しくはGHEの管理者にお問い合わせください。
## サポーター サブスクリプション
開発者([@h13i32maru](https://twitter.com/h13i32maru))を支援してくださる方は「[Support Subscription](https://h13i32maru.jp/supporter/)」から少額サブスクリプションをしていただけると大変うれしいです。
## フィードバック
フィードバックはお気軽にお寄せください。Twitterの[#jasperapp](https://twitter.com/hashtag/jasperapp)やJasperについてのブログ記事などを書いてもらえると非常に嬉しいです。不具合や機能要望は[jasperapp/jasper](https://github.com/jasperapp/jasper)にお願いします。可能な範囲で対応していきます。
## 競合
Jasperと同様にissueの閲覧や通知を管理するツールは現時点(2020.09)で次のようなものがあります。
| ツール | Active | 期間 |
| ------------------------------------------------------- | ------ | ------------------ |
| [Jasper](https://jasperapp.io/) | ✅ | 2016.06 \~ 2020.07 |
| [Trailer](http://ptsochantaris.github.io/trailer/) | ✅ | 2013.08 \~ 2020.09 |
| [DevHub](https://devhubapp.com/) | ✅ | 2017.05 \~ 2020.08 |
| [Octobox](https://octobox.io/) | ✅ | 2016.12 \~ 2020.09 |
| [GitHawk](http://githawk.com/) | ✅ | 2017.06 \~ 2020.05 |
| [Deck](https://tilfin.github.io/deck/) | | 2016.03 \~ 2019.12 |
| [faao](https://github.com/azu/faao) | | 2017.05 \~ 2019.12 |
| [Cashew](https://github.com/bellebethcooper/cashew) | | 2017.11 \~ 2019.04 |
| [Bee](http://www.neat.io/bee/github-issues-client.html) | | 2013.08 \~ 2018.09 |
| [Gitscout](https://gitscout.com/) | | 2015.11 \~ 2017.05 |
| [Ship](https://www.realartists.com/blog/ship-20.html) | | 2016.01 \~ 2017.01 |
| [DeckHub](https://getdeckhub.com/) | | 2016.02 \~ 2016.04 |
| [BugHub](http://www.bughubapp.com/) | | 2013.04 \~ 2015.11 |
## 記事
開発者の記事
* [JasperというGitHub Issue Readerを作りました - blog.h13i32maru.jp](http://blog.h13i32maru.jp/entry/2016/06/08/090000)
* [GitHub用のIssue Reader「Jasper」の開発を振り返ってみる - blog.h13i32maru.jp](http://blog.h13i32maru.jp/entry/2016/12/11/184433)
* [Jasper(GitHub用のIssue Reader)を無料にしました - blog.h13i32maru.jp](https://blog.h13i32maru.jp/entry/2018/07/17/083215)
* [ストレスフリーなGitHubのIssue生活 - techlife.cookpad.com](http://techlife.cookpad.com/entry/2017/03/14/100000)
* [Project of the Week: Jasper - electronjs.o](https://www.electronjs.org/blog/jasper)
ユーザの記事
* [GithubのISSUEでなにやらやるなら、Jasperが便利だぞ！の話 - uzulla.hateblo.jp](http://uzulla.hateblo.jp/entry/2016/07/13/021425)
* [GitHub Issue Reader の Jasper を1週間使っての所感 - ohbarye.hatenablog.jp](http://ohbarye.hatenablog.jp/entry/2016/11/19/004719)
* [Check my favorite OSS with Jasper - blog.lorentzca.me](https://blog.lorentzca.me/check-my-favorite-oss-with-jasper/)
* [最近使い始めてよかった３つのMacアプリ - medium.com](https://medium.com/@y_koh/%E6%9C%80%E8%BF%91%E4%BD%BF%E3%81%84%E5%A7%8B%E3%82%81%E3%81%A6%E3%82%88%E3%81%8B%E3%81%A3%E3%81%9F%EF%BC%93%E3%81%A4%E3%81%AEmac%E3%82%A2%E3%83%97%E3%83%AA-2e39bc77c925#.j1hugdgm7)
* [Github Issueを管理するJasperを買った - kechol.hatenablog.jp](http://kechol.hatenablog.jp/entry/jasper-a-github-issue-tracker)
* [GitHub Issue Reader「Jasper」をデザイナーにもオススメしたい - transitkix.hatenablog.jp](http://transitkix.hatenablog.jp/entry/2017/08/10/231124)
* [jasperがよかった - medium.com](https://medium.com/@naomeme/jasper%E3%81%8C%E3%82%88%E3%81%8B%E3%81%A3%E3%81%9F-fb70ebd117c0)
* [Jasper。プロダクトマネージャーがボトルネックとならないための最高のツール - quipper.hatenablog.com](https://quipper.hatenablog.com/entry/2018/06/28/120000)