https://github.com/yankeexe/good-first-issues
Find good first issues from your commandline! 🚀
https://github.com/yankeexe/good-first-issues
beginner-friendly cli cli-app github github-api good-first-issue hacktoberfest python-cli
Last synced: about 2 months ago
JSON representation
Find good first issues from your commandline! 🚀
- Host: GitHub
- URL: https://github.com/yankeexe/good-first-issues
- Owner: yankeexe
- License: mit
- Created: 2020-09-29T11:15:03.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-02-03T08:16:24.000Z (5 months ago)
- Last Synced: 2025-05-11T04:11:27.760Z (about 2 months ago)
- Topics: beginner-friendly, cli, cli-app, github, github-api, good-first-issue, hacktoberfest, python-cli
- Language: Python
- Homepage: https://pypi.org/project/good-first-issues/
- Size: 95.7 KB
- Stars: 116
- Watchers: 3
- Forks: 31
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
Good First Issues
Find good first issues right from your CLI!
## 📦 Installation
> Requires **Python 3.9 or higher**.
```bash
$ pip install good-first-issues --upgrade
```
The CLI uses the alias `gfi` to run commands.
## Contents
- [📦 Installation](#-installation)
- [🔑 Create GitHub Personal Access Token](#-create-github-personal-access-token)
- [🚀 Usage](#-usage)
- [🏢 Query all repos in an organization](#-query-all-repos-in-an-organization)
- [📦 Query a single repo in an organization](#-query-a-single-repo-in-an-organization)
- [👨💻 Query all repos in a user profile](#-query-all-repos-in-a-user-profile)
- [📦 Query a single repo in a user profile.](#-query-a-single-repo-in-a-user-profile)
- [🐙 Query all repos with topic `hacktoberfest`](#-query-all-repos-with-topic-hacktoberfest)
- [Query all repos with topic 'hacktoberfest' in an organization or in a user profile](#query-all-repos-with-topic-hacktoberfest-in-an-organization-or-in-a-user-profile)
- [📏 Search for issues within a certain period](#-search-for-issues-within-a-certain-period)
- [⚖️ Limit output](#️-limit-output)
- [🌐 View issues on browser](#-view-issues-on-browser)
- [👀 Show the CLI version](#-show-the-cli-version)
- [🔨 Contributing](#-contributing)
### 🔑 Create GitHub Personal Access Token
The CLI requires GitHub Personal Access Token to make requests to the GitHub API.
> Get [GitHub Fine-grained Personal Access Token](https://github.com/settings/tokens?type=beta)
You can add a Description to your token, select "Public Repositories (read-only)" and select _Generate token_.
**Provide token to CLI:**
```bash
$ gfi config
```
Token is stored locally on `/home//.gfi/good-first-issues` file.
**Token in envrionment variable:**
Store the token with the name `GFITOKEN` in your environment.
## 🚀 Usage
GitHub provides API to fetch user and organization data. [Personal Access Token](#create-github-personal-access-token) is required for authentication and data fetching.
### 🏢 Query all repos in an organization
```bash
$ gfi search "rust-lang"
```
> Demo
> 
### 📦 Query a single repo in an organization
```bash
$ gfi search "facebook" --repo "jest"
```
> Demo
> 
### 👨💻 Query all repos in a user profile
```bash
$ gfi search "yankeexe" --user
```
> Demo
> 
### 📦 Query a single repo in a user profile.
`--user` flag not required here.
```bash
$ gfi search "yankeexe" --repo "good-first-issues"
```
> Demo
> 
### 🐙 Query all repos with topic `hacktoberfest`
```bash
$ gfi search --hacktoberfest
$ gfi search -hf
$ gfi search -hf --period "30 days"
$ gfi search -hf --limit 10 --period "48 hours"
```
> Demo
> 
### 📏 Search for issues within a certain period
By default, no period is set and users are shown whatever data is fetched from the GitHub API.
To filter good first issues within a certain period, use the following commands:
```bash
# Query all organization repos
$ gfi search "rust-lang" -p "30 hours"
# Query a specific repo in an organization
$ gfi search "rust-lang" --repo "rust" -p "30 mins"
# Query repos with the topic hacktoberfest
$ gfi search -hf -p "100 days"
# Query all user repos
$ gfi search "yankeexe" --user -p "600 hrs"
# Query a specific repo of a user
$ gfi search "yankeexe" --user --repo "good-first-issues" -p "600 days"
```
```bash
# Example Usage:
--period 1 m,min,mins,minutes
--period 2 h,hr,hour,hours,hrs
--period 3 d,day,days
```
### ⚖️ Limit output
The output is limited to display 10 issues by default. Use `--limit` flag to set the number of issues for output or `--all` for no limits.
Limit the issues to 12
```bash
$ gfi search "facebook" --limit 12
```
> Demo
> 
View all issues found.
```bash
$ gfi search "rust-lang" --all
```
### 🌐 View issues on browser
It's hard to navigate through all the issues when you have the `--all` flag enabled, you can view the issues on your browser with ease using the `--web` flag.
```bash
$ gfi search "facebook" --all --web
```
> Demo
> 
### 👀 Show the CLI version
```bash
$ gfi version
```
## 🔨 Contributing
For guidance on setting up a development environment and how to make a contribution to `good-first-issues`, see the [contributing guidelines](https://github.com/yankeexe/good-first-issues/blob/master/CONTRIBUTING.md).