A Git CLI designed for efficent project management
🙋 Why did we make this?
While the vanilla GitHub CLI is a fantastic developer tool that dramatically simplifies collaboration on a project, it lacks several features. We have to rely on the GUI to use some of them, such as Github projects and notifications.
The lack of these features was our motivation to build this project so that not only us but thousands of other CLI-loving devs can make their "Git" experience truly "good".
👷 Who are we?
👶 Getting Started
You'll need to have Python (>= 3.7) and
pip to get started. If you don't have them installed already, see the official docs!
Once you're done, move on to the next steps below. ⬇
$ pip install gitgood
Yep, that's it. ⚡
After installation, check if
gg is actually up and running like:
$ gg Usage: gg [OPTIONS] COMMAND [ARGS]... Here to help! ✨ ...
And you're set! 🚀
⚙ Basic configuration
You'll need your GitHub personal access token to make use of the CLI. You can make a new token here.
If you already have one, you can make a
.gg file in your home folder like this (recommended):
GG_PAT=<your super secret token>
And the CLI will automatically pick it up, or you can set the
GG_PAT environment variable yourself.
If this is all too much, don't fret! The first time you run
gg on the CLI, you'll get instructions on how to make one. Easy-peezy, lemon-squeezy. 🍋
🧱 Building from source
It is highly recommended you use Poetry or virtual environments for building the project (such as Python's
venv or the
virtualenv module) to easily manage dependencies.
$ git clone firstname.lastname@example.org:QEDK/gitgood.git $ cd gitgood $ pip3 install poetry $ poetry install $ poetry shell
Or if you prefer it hardball, just do
pip3 install -r requirements.txt.
You can also use
poetry to build the binaries:
$ poetry build
You're now ready to work on
There are two commands that operate in the app. They are "project" and "notifs".
- Project Management: The command "project" deals with tasks realted to viewing/managing the projects and their content(columns, cards etc)
Arguments: repo_address : this is the address of the repository in the form of user_name/repository_name. For ex: "QEDK/gitgood"
- Notification management: The command "notifs" deals with the tasks related to notifications.
Arguments: This command have following arguments.
- LIMIT : This argument is OPTIONAL and prints only [LIMIT] no of notifications.
- read(type: string) : This is used to mark a specific no. of notifications as READ. Use 'A' for all notifications or any.
- repo-notif (type: string): This prints all the notifications in the repository mentioned in the argument.
Printing all the projects in the given repository.
$ gg project <repo_address>
$ gg project QEDK/gitgood
Printing all the columns in all the projects in the given repository.
$ gg project <repo_address> --columns
$ gg project QEDK/gitgood --columns
Printing all the cards in a particular project.
$ gg project <repo_address> --project-card <project_name>
$ gg project QEDK/gitgood --project-card App
Moving a card from one column to another.
$ gg project <repo_address> --move <card_id>
$ gg project QEDK/gitgood --move 1234567
Printing all the notifications of the user.
$ gg notifs [LIMIT] (type: int)
$ gg notifs 2
Making the notifications as read. Once, marked they won't appear again on notifs command.
$ gg notifs --read [read]
$ gg notifs --read 2
Printing all the notifications of a particular repository.
$ gg notifs --repo-notifs <repository_name>
$ gg notifs --repo-notifs gitgood
- Python - Programming Language
- Typer - Python CLI library
- Github Api - API
- PyGithub - Github API Package
- flask8 - Linting tool
- Poetry - Packaging and publishing
This project is released under a free and open-source software license, Apache License 2.0 or later (LICENSE or https://www.apache.org/licenses/LICENSE-2.0). The documentation is also released under a free documentation license, namely the GFDL v1.3 license or later.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.