Skip to content

INSTALL.md

Latest commit

 

History

History
305 lines (218 loc) · 5.6 KB

INSTALL.md

File metadata and controls

305 lines (218 loc) · 5.6 KB

Installation Guide

Method 1: Install from Source (Recommended for Development)

Prerequisites

  • Python 3.10 or higher
  • Poetry (Python dependency manager)
  • Git

Steps

  1. Clone the repository:

    git clone https://github.com/yourusername/patchsmith.git
cd patchsmith

  2. Install dependencies:

    poetry install

  3. Verify installation:

    poetry run patchsmith --version

  4. Run Patchsmith:

    poetry run patchsmith --help

Optional: Install in virtual environment

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with Poetry
poetry install

# Patchsmith is now available as a command
patchsmith --help

Method 2: Install from Built Package

Build the package

# From the project root
poetry build

This creates two files in dist/:

  • patchsmith-0.1.0.tar.gz (source distribution)
  • patchsmith-0.1.0-py3-none-any.whl (wheel)

Install the wheel

pip install dist/patchsmith-0.1.0-py3-none-any.whl

Or install from the source distribution:

pip install dist/patchsmith-0.1.0.tar.gz

Verify installation

patchsmith --version

Method 3: Install from PyPI (Coming Soon)

Once published to PyPI, you'll be able to install with:

pip install patchsmith

External Dependencies

Patchsmith requires these external tools:

1. CodeQL CLI

CodeQL is required for static analysis.

macOS (Homebrew):

brew install codeql

Linux/macOS (Manual):

# Download from GitHub releases
wget https://github.com/github/codeql-cli-binaries/releases/latest/download/codeql-linux64.zip
unzip codeql-linux64.zip
export PATH="$PWD/codeql:$PATH"

# Add to your shell profile for persistence
echo 'export PATH="/path/to/codeql:$PATH"' >> ~/.bashrc

Verify installation:

codeql version

2. Anthropic API Key

Required for AI-powered features (triage, detailed analysis, fix generation).

  1. Sign up at https://console.anthropic.com/
  2. Generate an API key
  3. Configure the API key using one of these methods:

Option A: User config file (Recommended - most convenient)

Run patchsmith init and it will prompt you to save your API key:

patchsmith init --save-api-key

This saves your key to ~/.patchsmith/config.yaml with secure permissions (600).

Option B: Environment variable (Good for CI/CD or temporary use)

export ANTHROPIC_API_KEY='your-api-key-here'

Make it permanent by adding to your shell profile:

# For bash
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc

Option C: Manual user config file

Create ~/.patchsmith/config.yaml:

anthropic_api_key: 'your-api-key-here'

Then set secure permissions:

chmod 600 ~/.patchsmith/config.yaml

Priority: Environment variable > User config file

3. Git (Optional but Recommended)

Git is required for fix application features (branching, commits).

Install:

  • macOS: brew install git or comes pre-installed
  • Linux: apt-get install git or yum install git
  • Windows: Download from https://git-scm.com/

Troubleshooting

"Command not found: patchsmith"

If you installed with Poetry:

# Use poetry run
poetry run patchsmith --help

# OR activate the virtual environment
poetry shell
patchsmith --help

If you installed with pip:

# Check if it's in your PATH
which patchsmith

# If not found, your Python scripts directory may not be in PATH
# Add it to PATH (adjust path as needed):
export PATH="$HOME/.local/bin:$PATH"

"CodeQL not found"

Make sure CodeQL is installed and in your PATH:

# Check installation
which codeql
codeql version

# If not found, add to PATH
export PATH="/path/to/codeql:$PATH"

"ANTHROPIC_API_KEY not set"

# Set the environment variable
export ANTHROPIC_API_KEY='your-key'

# Verify it's set
echo $ANTHROPIC_API_KEY

"ImportError" or "ModuleNotFoundError"

If you get import errors:

# Reinstall dependencies
poetry install --no-cache

# OR with pip
pip install --force-reinstall -e .

Permission errors on macOS/Linux

# Install for current user only
pip install --user dist/patchsmith-0.1.0-py3-none-any.whl

Development Installation

For development with editable installation:

# Clone and install in editable mode
git clone https://github.com/yourusername/patchsmith.git
cd patchsmith
poetry install

# Now code changes take effect immediately
poetry run patchsmith --help

Uninstallation

If installed with pip:

pip uninstall patchsmith

If installed with Poetry:

# Remove virtual environment
poetry env remove python

Next Steps

After installation:

  1. Verify everything works:

    patchsmith --version
patchsmith --help
codeql version
echo $ANTHROPIC_API_KEY

  2. Initialize a project:

    cd /path/to/your/project
patchsmith init

  3. Run your first analysis:

    patchsmith analyze

  4. Read the documentation:

Getting Help

If you encounter issues:

  1. Check this troubleshooting section
  2. Review the CLI Guide
  3. Search GitHub Issues
  4. Open a new issue with:
    • Your OS and Python version
    • Complete error message
    • Steps to reproduce