Installation & Requirements

Before using GitLegends, ensure your system meets the following prerequisites and then follow the installation steps. GitLegends is a Python-based CLI tool, so you can install it via pip or from source.

Prerequisites

• Git: GitLegends uses the Git command-line tool. Make sure Git is installed and accessible in your system’s PATH. You can verify by running git --version. If not installed, download it from the official site.
• GitHub CLI (gh): GitLegends relies on GitHub’s official CLI for creating repos, pull requests, and other GitHub operations. Install the gh CLI and log in (gh auth login) or ensure you have a valid GITHUB_TOKEN/GH_TOKEN set for authentication. Verify by running gh --version.
• Python 3.9 or newer: GitLegends requires Python (3.9+). Check your Python version with python3 --version. If you plan to install via pip, having pip (the Python package installer) is necessary.
• PyYAML (optional): If you intend to use YAML config files for GitLegends (to predefine settings), the PyYAML library is needed. This is typically installed automatically with GitLegends. If it isn’t, you can install it manually via pip install pyyaml.

Installing GitLegends

There are a couple of ways to install GitLegends:

1. Install via pip (PyPI)

If GitLegends is published on PyPI, you can install it like any other Python package:

pip install legends

This will install the legends CLI tool globally (or in your active virtual environment). After installation, verify by running:

legends --help

This should display the help text and available commands, confirming that GitLegends is installed and accessible.

2. Install from source (editable mode)

If you have the GitLegends source code (for example, by cloning the GitHub repository), you can install it in “editable” mode (useful for development or the latest unreleased version):

# Clone the GitLegends repository from GitHub (replace URL with the actual repo URL)
git clone https://github.com/yourusername/gitlegends.git
cd gitlegends

# Create a virtual environment (optional but recommended)
python3 -m venv .venv
source .venv/bin/activate

# Upgrade pip and install GitLegends in editable mode with dev extras
pip install --upgrade pip
pip install -e ".[dev]"

The above steps will set up a virtual environment, then install the legends package in editable mode (so any changes to the source code will reflect when you run the CLI). The .[dev] extras installation also brings in development tools (like testing and linting tools) which you may skip if you only want to use the tool, not develop it.

After installing from source, you can again run legends --help to ensure the CLI is working.

3. Using the provided Makefile (if available)

If the source repository includes a Makefile with setup commands, you can often do:

make install

This would typically create the virtual environment and install the package for you (the equivalent of the steps above). There might also be other convenience targets like make verify-env (to check that Git, gh, and other requirements are in place) and make run-help (to show the help). Check the repository’s README or Makefile for available commands.

Verifying Your Environment

After installation, it’s a good idea to verify that all components are working together:

• Run legends --version to get the version of GitLegends installed.
• Run git --version and gh --version to ensure both Git and GitHub CLI are accessible.
• If you haven’t already, log in to GitHub via gh auth login or ensure your GITHUB_TOKEN is set. GitLegends will use your GitHub credentials to create repositories and PRs.
• (Optional) There is a script scripts/verify_env.sh in the source repository. You can execute this script to perform a comprehensive check that Git, GitHub CLI, authentication, and Git config (user name/email) are all set up correctly for GitLegends.