gh-echo 0.3.0

A command-line tool built to obtain in-depth, actionable information about GitHub repositories.

A command-line tool built to obtain in-depth, actionable information about GitHub repositories that is often challenging to decipher manually

Table of Contents

• Usage
• Installing via PyPi
  • Prerequisites
  • Setup Instructions
    • For macOS/Linux
    • For Windows
• Running the Tool Locally
  • Prerequisites
  • Setup Instructions
    • 1. Clone the Repository
    • 2. Set Up Environment Variables
    • 3. Install Required Dependencies
    • 4. Activate the Virtual Environment
    • 5. Running the CLI Tool Locally
      • On Windows
      • On macOS and Linux
• Running Using Docker
  • On Windows
  • On macOS and Linux
• Troubleshooting
• Further Usage Instructions
  • Arguments
  • Options
  • Status Codes
• More about github-echo
  • Information drawn from the GitHub API
  • GenAI Integration
• Contributing
• License
• Author

Usage

You can use this tool in two ways:

1. Install via PyPi: Quickly set up the tool with a simple pip install.
2. Run Locally: Clone the repository and run it directly on your machine for development or testing.

Installing via PyPi

Prerequisites

1. Python3+: Ensure Python3 is installed on your system. You can download it from python.org.

Setup Instructions

1. Open a terminal or command prompt.

2. Install the tool via PyPi:

   pip install gh-echo
   

3. Once installed, you need to set the required environment variables in your shell configuration. Here are the steps for different systems:

For macOS/Linux

• Open your terminal.

• Add the environment variables to your shell configuration file (e.g., .bashrc, .zshrc, etc.)

  export GOOGLE_GEMINI_API_KEY='Your Google Gemini API Key' # If you are using Gemini
  export GROQ_API_KEY='Your Groq API Key' # If you are using Groq's API
  export GITHUB_API_TOKEN='Your GitHub API Token'
  export GITHUB_API_VERSION='2022-11-28'
  

  • Replace 'Your Google Gemini API Key' with your Google Gemini API Key if you want to use Google Gemini LLM to extract insights.
  • Replace 'Your Groq API Key' with your Groq API Key if you want to use Groq's API to extract insights.
  • Replace 'Your API Token' with your GitHub Access Token.
  • You can leave the GITHUB_API_VERSION as is unless you really want to change it.

• Run source ~/.bashrc (or source ~/.zshrc for Zsh) to apply the changes.

For Windows

• Open PowerShell as Administrator.

• Set the environment variables:

  [System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_API_KEY', 'Your Google Gemini API Key', 'User') # If you are using Gemini
  [System.Environment]::SetEnvironmentVariable('GROQ_API_KEY', 'Your Groq API Key', 'User') # If you are using Groq's API
  [System.Environment]::SetEnvironmentVariable('GITHUB_API_TOKEN', 'Your GitHub API Token', 'User')
  [System.Environment]::SetEnvironmentVariable('GITHUB_API_VERSION', '2022-11-28', 'User')
  

  • Replace 'Your Google Gemini API Key' with your Google Gemini API Key if you want to use Google Gemini LLM to extract insights.
  • Replace 'Your Groq API Key' with your Groq API Key if you want to use Groq's API to extract insights.
  • Replace 'Your API Token' with your GitHub Access Token.
  • You can leave the GITHUB_API_VERSION as is unless you really want to change it.

• Now you can run the CLI tool from anywhere in your terminal:

  gh-echo <GITHUB_REPOSITORY_URL> [OPTIONS]
  

  Example:

  gh-echo https://github.com/user/repo --output results.md
  

Running the Tool Locally

Prerequisites

1. Python3+: Ensure Python3 is installed on your system. You can download it from python.org.
2. Git: Ensure Git is installed. You can download it from git-scm.com.
3. Poetry: Install Poetry by following the instructions at poetry.eustace.io.

Setup Instructions

1. Clone the Repository

First, clone the repository to your local machine:

git clone https://github.com/AryanK1511/github-echo
cd github-echo

2. Set Up Environment Variables

For running the tool locally, create a .env file in the root of the repository and add the following content:

GOOGLE_GEMINI_API_KEY='Your Google Gemini API Key' # If you are using Google Gemini
GROQ_API_KEY='Your Groq API Key' # If you are using Groq's API
GITHUB_API_TOKEN='Your API Token'
GITHUB_API_VERSION='2022-11-28'

• Replace 'Your Google Gemini API Key' with your Google Gemini API Key if you want to use Google Gemini LLM to extract insights.
• Replace 'Your Groq API Key' with your Groq API Key if you want to use Groq's API to extract insights.
• Replace 'Your API Token' with your GitHub Access Token.
• You can leave the GITHUB_API_VERSION as is unless you really want to change it.

3. Install Required Dependencies

Install the necessary Python packages using Poetry:

poetry install

This will install all required dependencies and set up a virtual environment.

4. Activate the Virtual Environment

Activate the Poetry virtual environment with:

poetry shell

5. Running the CLI Tool Locally

Once the environment is set up and dependencies are installed, you can run the tool locally.

On Windows

1. Open Command Prompt or PowerShell.

2. Navigate to the project directory:

   cd path\to\github-echo
   

3. Run the script:

   python _main.py <GITHUB_REPOSITORY_URL> [OPTIONS]
   

   Example:

   python _main.py https://github.com/user/repo --output results.md
   

On macOS and Linux

1. Open Terminal.

2. Navigate to the project directory:

   cd /path/to/github-echo
   

3. Make the script executable (if needed):

   chmod +x _main.py
   

4. Run the script:

   python _main.py <GITHUB_REPOSITORY_URL> [OPTIONS]
   

   Example:

   python _main.py https://github.com/user/repo --output results.md
   

Additional Information

• For Help: Run ./_main.py --help or python _main.py --help to see the available options and usage instructions.
• For Version: Use the --version or -v flag to get the version number.

Running Using Docker

WARNING: If you run using Docker, it will deprive you of a lot of features that the command line tool offers. Pretty print becomes unavailable and overall it doesn't look very pretty. It's always recommended to run this tool locally for development purposes.

Cloning the repo and setting the environment variables

• First, clone the repository to your local machine:

  git clone https://github.com/AryanK1511/github-echo
  cd github-echo
  

• Next, navigate to the Dockerfile in the root of this repository and fill in the environment variables

ENV GOOGLE_GEMINI_API_KEY='Your Google Gemini API Key' # If you are using Google Gemini
ENV GROQ_API_KEY='Your Groq API Key' # If you are using Groq's API
ENV GITHUB_API_TOKEN='Your API Key'
ENV GITHUB_API_VERSION='2022-11-28'

• Replace 'Your Google Gemini API Key' with your Google Gemini API Key if you want to use Google Gemini LLM to extract insights.
• Replace 'Your Groq API Key' with your Groq API Key if you want to use Groq's API to extract insights.
• Replace 'Your API Token' with your GitHub Access Token.
• You can leave the GITHUB_API_VERSION as is unless you really want to change it.

On Windows

• Install Docker: Download and install Docker Desktop from Docker’s website.

• Build the Docker Image: Open Command Prompt or PowerShell, navigate to the project directory, and build the Docker image:

  docker build -t gh-echo .
  

• Run the Docker Container: Once the image is built, you can run a container with the following command:

  docker run --rm gh-echo <GITHUB_REPOSITORY_URL> [OPTIONS]
  

  Example:

  docker run --rm gh-echo https://github.com/user/repo --output results.md
  

On macOS and Linux

• Install Docker: Follow instructions at Docker’s website.

• Build the Docker Image: Open Terminal, navigate to the project directory, and build the Docker image:

  docker build -t gh-echo .
  

• Run the Docker Container: Once the image is built, you can run a container with the following command:

  docker run --rm gh-echo <GITHUB_REPOSITORY_URL> [OPTIONS]
  

  Example:

  docker run --rm gh-echo https://github.com/user/repo --output results.md
  

Troubleshooting

• Invalid GitHub URL: Ensure the URL is correct and follows the format https://github.com/owner/repo.
• Connection Issues: Check your internet connection and API tokens.
• Permission Errors: On Windows, ensure you have the necessary permissions to run scripts. On macOS/Linux, ensure the script has execution permissions.

Further Usage Instructions

_main.py [OPTIONS] GITHUB_REPOSITORY_URL COMMAND [ARGS]..._

Arguments

Argument	Tsype	Description	Default	Required
github_repository_url	TEXT	The URL of the GitHub repository to analyze	None	Yes

Options

Option	Shortcut	Type	Description	Default
--version	-v	Flag	Get the version number	N/A
--temperature	-t	Option	Set the temperature for the model's output randomness	0.5
--output	-o	PATH	Path to the output file	None
--help		Flag	Show this message and exit	N/A
--token-usage		Flag	Displays token usage to the user via stderr	N/A

Status Codes

When executing the command, the tool returns the following status codes to indicate the outcome of the operation:

• Status Code 0: Success

  • This status code indicates that the operation completed successfully without any errors. All results are processed as expected.

• Status Code 1: Error

  • This status code indicates that an error occurred during the execution of the command. An appropriate error message will be displayed to the user, detailing what went wrong. Common reasons for receiving this status code include:
    • Invalid GitHub repository URL.
    • Network connectivity issues.
    • Problems with data retrieval or processing.
    • Missing API Keys.
    • Something wrong on the server side with any of the AI providers used.

More about github-echo

Information drawn from the GitHub API

The tool fetches the following key information about GitHub repositories:

• Repository Metadata: Name, description, owner, URL, and other basic information.
• Contributors: Details about contributors, including their usernames, IDs, and avatars.
• Issues and Pull Requests: Information about open and closed issues and pull requests, including titles, states, and comments.
• Labels: Labels associated with issues and pull requests.
• Activity Data: Data related to repository activity, such as commit history and contributions.

GenAI Integration

Repo Insights uses GenAI to analyze the fetched repository data. This provides advanced capabilities for:

• Summary Generation: Creating comprehensive summaries based on the repository data.
• Insight Extraction: Identifying key patterns and insights that are not immediately obvious from raw data.

How It Works:

1. Data Fetching: The tool queries GitHub's API to gather repository data.
2. Data Processing: The fetched data is processed and formatted.
3. AI Analysis: The processed data is sent to an LLM, which analyzes it and generates a detailed summary.
4. Summary Output: The summary is either displayed in the terminal or saved to a specified file.

Contributing

We welcome contributions to improve Repo Insights. If you have suggestions, bug reports, or enhancements, please open an issue or submit a pull request.

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/your-feature).
3. Commit your changes (git commit -am 'Add new feature').
4. Push to the branch (git push origin feature/your-feature).
5. Create a new Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Aryan Khurana