<p align="center">
<img src="https://i.imgur.com/vTgsBoQ.png" width="100" alt="Good First Issues"/></a>
</p>
<h1 align="center"><strong> Good First Issues</strong> </h1>
<p align="center"><strong>Find good first issues right from your CLI!</strong></p>
<p align="center">
<img src="https://img.shields.io/pypi/v/good-first-issues?style=flat-square&color=black"/>
<img src="https://img.shields.io/pypi/pyversions/good-first-issues?style=flat-square&color=black" />
<img src="https://img.shields.io/pypi/l/good-first-issues?style=flat-square&color=black"/>
<img src="https://static.pepy.tech/badge/good-first-issues"/>
</p>
## 📦 Installation
> Requires **Python 3.9 or higher**.
```bash
$ pip install good-first-issues --upgrade
```
The CLI uses the alias `gfi` to run commands.
<img src="https://i.imgur.com/UM4e9vQ.png" width="800" />
## 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/<username>/.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"
```
> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/B8zRd1z.gif" width="700" alt="demo of timezone cli search" />
</details>
### 📦 Query a single repo in an organization
```bash
$ gfi search "facebook" --repo "jest"
```
> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/XayYGEd.gif" width="700" alt="demo of timezone cli search" />
</details>
### 👨💻 Query all repos in a user profile
```bash
$ gfi search "yankeexe" --user
```
> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/LnPrk4A.gif" width="700" alt="demo of timezone cli search" />
</details>
### 📦 Query a single repo in a user profile.
`--user` flag not required here.
```bash
$ gfi search "yankeexe" --repo "good-first-issues"
```
> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/ywGT9VQ.gif" width="700" alt="demo of timezone cli search" />
</details>
### 🐙 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"
```
> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/6Ch5BFG.gif" width="700" alt="demo of timezone cli search" />
</details>
### 📏 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
```
> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/WdXhA4Z.gif" width="700" alt="demo of timezone cli search" />
</details>
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
```
> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/AukVqdk.gif" width="700" alt="demo of timezone cli search" />
</details>
### 👀 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).
Raw data
{
"_id": null,
"home_page": "https://github.com/yankeexe/good-first-issues",
"name": "good-first-issues",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Yankee Maharjan",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d9/fb/aabe409d2989ca623698352768108bae7797ecb29cf84da2584ae6939b08/good-first-issues-2.1.5.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://i.imgur.com/vTgsBoQ.png\" width=\"100\" alt=\"Good First Issues\"/></a>\n</p>\n\n<h1 align=\"center\"><strong> Good First Issues</strong> </h1>\n<p align=\"center\"><strong>Find good first issues right from your CLI!</strong></p>\n\n<p align=\"center\">\n<img src=\"https://img.shields.io/pypi/v/good-first-issues?style=flat-square&color=black\"/>\n<img src=\"https://img.shields.io/pypi/pyversions/good-first-issues?style=flat-square&color=black\" />\n<img src=\"https://img.shields.io/pypi/l/good-first-issues?style=flat-square&color=black\"/>\n<img src=\"https://static.pepy.tech/badge/good-first-issues\"/>\n\n</p>\n\n## \ud83d\udce6 Installation\n\n> Requires **Python 3.9 or higher**.\n\n```bash\n$ pip install good-first-issues --upgrade\n```\n\nThe CLI uses the alias `gfi` to run commands.\n\n<img src=\"https://i.imgur.com/UM4e9vQ.png\" width=\"800\" />\n\n## Contents\n- [\ud83d\udce6 Installation](#-installation)\n - [\ud83d\udd11 Create GitHub Personal Access Token](#-create-github-personal-access-token)\n- [\ud83d\ude80 Usage](#-usage)\n - [\ud83c\udfe2 Query all repos in an organization](#-query-all-repos-in-an-organization)\n - [\ud83d\udce6 Query a single repo in an organization](#-query-a-single-repo-in-an-organization)\n - [\ud83d\udc68\u200d\ud83d\udcbb Query all repos in a user profile](#-query-all-repos-in-a-user-profile)\n - [\ud83d\udce6 Query a single repo in a user profile.](#-query-a-single-repo-in-a-user-profile)\n - [\ud83d\udc19 Query all repos with topic `hacktoberfest`](#-query-all-repos-with-topic-hacktoberfest)\n - [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)\n - [\ud83d\udccf Search for issues within a certain period](#-search-for-issues-within-a-certain-period)\n - [\u2696\ufe0f Limit output](#\ufe0f-limit-output)\n - [\ud83c\udf10 View issues on browser](#-view-issues-on-browser)\n - [\ud83d\udc40 Show the CLI version](#-show-the-cli-version)\n- [\ud83d\udd28 Contributing](#-contributing)\n\n### \ud83d\udd11 Create GitHub Personal Access Token\n\nThe CLI requires GitHub Personal Access Token to make requests to the GitHub API.\n\n> Get [GitHub Fine-grained Personal Access Token](https://github.com/settings/tokens?type=beta)\n\nYou can add a Description to your token, select \"Public Repositories (read-only)\" and select\u00a0_Generate token_.\n\n**Provide token to CLI:**\n\n```bash\n$ gfi config\n```\n\nToken is stored locally on `/home/<username>/.gfi/good-first-issues` file.\n\n**Token in envrionment variable:**\n\nStore the token with the name `GFITOKEN` in your environment.\n\n## \ud83d\ude80 Usage\n\nGitHub provides API to fetch user and organization data. [Personal Access Token](#create-github-personal-access-token) is required for authentication and data fetching.\n\n### \ud83c\udfe2 Query all repos in an organization\n\n```bash\n$ gfi search \"rust-lang\"\n```\n\n> <details><summary><strong>Demo</strong></summary>\n> <img src = \"https://i.imgur.com/B8zRd1z.gif\" width=\"700\" alt=\"demo of timezone cli search\" />\n\n</details>\n\n### \ud83d\udce6 Query a single repo in an organization\n\n```bash\n$ gfi search \"facebook\" --repo \"jest\"\n```\n\n> <details><summary><strong>Demo</strong></summary>\n> <img src = \"https://i.imgur.com/XayYGEd.gif\" width=\"700\" alt=\"demo of timezone cli search\" />\n\n</details>\n\n### \ud83d\udc68\u200d\ud83d\udcbb Query all repos in a user profile\n\n```bash\n$ gfi search \"yankeexe\" --user\n```\n\n> <details><summary><strong>Demo</strong></summary>\n> <img src = \"https://i.imgur.com/LnPrk4A.gif\" width=\"700\" alt=\"demo of timezone cli search\" />\n\n</details>\n\n### \ud83d\udce6 Query a single repo in a user profile.\n\n`--user` flag not required here.\n\n```bash\n$ gfi search \"yankeexe\" --repo \"good-first-issues\"\n```\n\n> <details><summary><strong>Demo</strong></summary>\n> <img src = \"https://i.imgur.com/ywGT9VQ.gif\" width=\"700\" alt=\"demo of timezone cli search\" />\n\n</details>\n\n\n### \ud83d\udc19 Query all repos with topic `hacktoberfest`\n\n```bash\n$ gfi search --hacktoberfest\n\n$ gfi search -hf\n\n$ gfi search -hf --period \"30 days\"\n\n$ gfi search -hf --limit 10 --period \"48 hours\"\n```\n\n> <details><summary><strong>Demo</strong></summary>\n> <img src = \"https://i.imgur.com/6Ch5BFG.gif\" width=\"700\" alt=\"demo of timezone cli search\" />\n\n</details>\n\n\n### \ud83d\udccf Search for issues within a certain period\n\nBy default, no period is set and users are shown whatever data is fetched from the GitHub API.\n\nTo filter good first issues within a certain period, use the following commands:\n\n```bash\n\n# Query all organization repos\n$ gfi search \"rust-lang\" -p \"30 hours\"\n\n# Query a specific repo in an organization\n$ gfi search \"rust-lang\" --repo \"rust\" -p \"30 mins\"\n\n# Query repos with the topic hacktoberfest\n$ gfi search -hf -p \"100 days\"\n\n# Query all user repos\n$ gfi search \"yankeexe\" --user -p \"600 hrs\"\n\n# Query a specific repo of a user\n$ gfi search \"yankeexe\" --user --repo \"good-first-issues\" -p \"600 days\"\n```\n\n```bash\n# Example Usage:\n--period 1 m,min,mins,minutes\n\n--period 2 h,hr,hour,hours,hrs\n\n--period 3 d,day,days\n\n```\n\n### \u2696\ufe0f Limit output\n\nThe 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.\n\nLimit the issues to 12\n\n```bash\n$ gfi search \"facebook\" --limit 12\n```\n\n> <details><summary><strong>Demo</strong></summary>\n> <img src = \"https://i.imgur.com/WdXhA4Z.gif\" width=\"700\" alt=\"demo of timezone cli search\" />\n\n</details>\n\nView all issues found.\n\n```bash\n$ gfi search \"rust-lang\" --all\n```\n\n### \ud83c\udf10 View issues on browser\n\nIt'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.\n\n```bash\n$ gfi search \"facebook\" --all --web\n```\n\n> <details><summary><strong>Demo</strong></summary>\n> <img src = \"https://i.imgur.com/AukVqdk.gif\" width=\"700\" alt=\"demo of timezone cli search\" />\n\n</details>\n\n### \ud83d\udc40 Show the CLI version\n\n```bash\n$ gfi version\n```\n\n## \ud83d\udd28 Contributing\n\nFor 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).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Find good first issues right from your CLI!",
"version": "2.1.5",
"project_urls": {
"Bug Reports": "https://github.com/yankeexe/good-first-issues/issues",
"Homepage": "https://github.com/yankeexe/good-first-issues",
"Source": "https://github.com/yankeexe/good-first-issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "89edd77448b7953e70077ffd042807bc2184d73018989eea3e9cc903ff16147b",
"md5": "974855a3f60a386c7a22e84be091894a",
"sha256": "3a74693cc81de88840e6a96b969932502768a95d4b273b443d2ff4452f7dcecd"
},
"downloads": -1,
"filename": "good_first_issues-2.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "974855a3f60a386c7a22e84be091894a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14670,
"upload_time": "2025-02-02T06:33:42",
"upload_time_iso_8601": "2025-02-02T06:33:42.786799Z",
"url": "https://files.pythonhosted.org/packages/89/ed/d77448b7953e70077ffd042807bc2184d73018989eea3e9cc903ff16147b/good_first_issues-2.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d9fbaabe409d2989ca623698352768108bae7797ecb29cf84da2584ae6939b08",
"md5": "41a3f07b42202c0bd02f9d47c3cd532f",
"sha256": "d90ec67ad24a29bf4e87946a344273e5937c6485929896528f88746739a5c035"
},
"downloads": -1,
"filename": "good-first-issues-2.1.5.tar.gz",
"has_sig": false,
"md5_digest": "41a3f07b42202c0bd02f9d47c3cd532f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 14203,
"upload_time": "2025-02-02T06:33:44",
"upload_time_iso_8601": "2025-02-02T06:33:44.746100Z",
"url": "https://files.pythonhosted.org/packages/d9/fb/aabe409d2989ca623698352768108bae7797ecb29cf84da2584ae6939b08/good-first-issues-2.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-02 06:33:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yankeexe",
"github_project": "good-first-issues",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "good-first-issues"
}
JSON
