Good First Issues

Find good first issues right from your CLI!

📦 Installation

Requires Python 3.9 or higher.

$ pip install good-first-issues --upgrade
Using uvx
$ uvx --from good-first-issues gfi

The CLI uses the alias gfi to run commands.

Contents

• 📦 Installation
  • 🔑 Create GitHub Personal Access Token
• 🚀 Usage
  • 🏢 Query all repos in an organization
  • 📦 Query a single repo in an organization
  • 👨‍💻 Query all repos in a user profile
  • 📦 Query a single repo in a user profile
  • 🐙 Query all repos with topic hacktoberfest
    • Query all repos with topic 'hacktoberfest' in an organization or in a user profile
  • 📏 Search for issues within a certain period
  • ⚖️ Limit output
  • 🌐 View issues on browser
  • 👀 Show the CLI version
• 🔨 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

You can add a Description to your token, select "Public Repositories (read-only)" and select Generate token.

Provide token to CLI:

$ gfi config

Token is stored locally on /home/<username>/.gfi/good-first-issues file.

Token in environment variable:

Store the token with the name GFITOKEN in your environment.

🚀 Usage

GitHub provides API to fetch user and organization data. Personal Access Token is required for authentication and data fetching.

🏢 Query all repos in an organization

$ gfi search "rust-lang"

Demo

📦 Query a single repo in an organization

$ gfi search "facebook" --repo "jest"

Demo

👨‍💻 Query all repos in a user profile

$ gfi search "yankeexe" --user

Demo

📦 Query a single repo in a user profile

--user flag not required here.

$ gfi search "yankeexe" --repo "good-first-issues"

Demo

🐙 Query all repos with topic hacktoberfest

$ 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:

# 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"

# 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

$ gfi search "facebook" --limit 12

Demo

View all issues found.

$ 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.

$ gfi search "facebook" --all --web

Demo

👀 Show the CLI version

$ 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.