Skip to content

README formatting and add installation verification #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

README formatting and add installation verification #41

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 64 additions & 75 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,51 @@
<p align="center">
<img src="https://i.imgur.com/vTgsBoQ.png" width="100" alt="Good First Issues"/></a>
<img src="https://i.imgur.com/vTgsBoQ.png" width="100" alt="Good First Issues"/>
</p>

<h1 align="center"><strong> Good First Issues</strong> </h1>
<p align="center"><strong>Find good first issues right from your CLI!</strong></p>
<h1 align="center">
<strong> Good First Issues</strong>
</h1>

<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"/>
<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**.
Requires **Python 3.9 or higher**.

```bash
$ pip install good-first-issues --upgrade

# Using uvx

$ uvx --from good-first-issues gfi
```

The CLI uses the alias `gfi` to run commands.

### ✓ Verify Installation

After installation, you can verify that `gfi` is installed correctly by checking the version:

```bash
$ gfi version
```

This should display the installed version of good-first-issues.

<img src="https://i.imgur.com/UM4e9vQ.png" width="800" />

## Contents
- [📦 Installation](#-installation)
- [🔑 Create GitHub Personal Access Token](#-create-github-personal-access-token)

- [📦 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)
Expand All @@ -51,100 +65,70 @@ 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
```
You can add a Description to your token, select "Public Repositories (read-only)" and select _Generate token_.

Token is stored locally on `/home/<username>/.gfi/good-first-issues` file.
When you run the CLI for the first time, you'll be prompted for the GitHub Personal Access Token.

**Token in environment variable:**

Store the token with the name `GFITOKEN` in your environment.
The token is stored locally in `~/.gfi/good-first-issues` file.

## 🚀 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"
$ gfi search "kubernetes"
```

> <details><summary><strong>Demo</strong></summary>
> <img src = "https://i.imgur.com/B8zRd1z.gif" width="700" alt="demo of timezone cli search" />

</details>
> <details>
> <summary>
> <strong>Demo</strong>
> </summary>
>
> <img src="https://i.imgur.com/OmfN76J.gif" width="700" alt="demo of timezone cli search" />
>
> </details>

### 📦 Query a single repo in an organization

```bash
$ gfi search "facebook" --repo "jest"
$ gfi search "rust-lang" --repo "rust"
```

> <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"
$ gfi search "yankeexe" --user --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" />
#### Query all repos with topic 'hacktoberfest' in an organization or in a user profile

</details>
```bash
# Query for an organization
$ gfi search "do-community" -hf

# Query for a user profile
$ gfi search "yankeexe" -hf --user
```

### 📏 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.
By default, the issues are filtered within 1 day. You can provide filter period using `--period` flag.

To filter good first issues within a certain period, use the following commands:
Pass period in minutes, hours or days.

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

Expand All @@ -161,11 +145,8 @@ $ 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
Expand All @@ -178,10 +159,14 @@ Limit the issues to 12
$ 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>
> <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.

Expand All @@ -197,10 +182,14 @@ It's hard to navigate through all the issues when you have the `--all` flag enab
$ 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>
> <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

Expand Down