Installation Guide¶

This guide provides comprehensive instructions for installing Gira on various platforms and environments.

📋 Requirements¶

System Requirements¶

Python: 3.8 or higher (3.8, 3.9, 3.10, 3.11, 3.12 supported)
Git: Required for version control integration
Terminal: With Unicode support for rich terminal output
Operating System: Windows, macOS, or Linux

Python Dependencies¶

Gira automatically installs these core dependencies: - typer[all] ≥ 0.16.0 - CLI framework - pydantic[email] ≥ 2.11.7 - Data validation - rich ≥ 14.0.0 - Terminal formatting - GitPython ≥ 3.1.44 - Git integration

🚀 Quick Start¶

Install from PyPI (Recommended)¶

pip install gira

Install from PyPI with Jira Integration¶

pip install gira[jira]

📦 Installation Methods¶

1. Standard Installation (PyPI)¶

Using pip¶

# Basic installation
pip install gira

# With Jira integration
pip install gira[jira]

# With all optional features
pip install gira[all]

Using pipx (Recommended for CLI tools)¶

# Install pipx if not already installed
python -m pip install pipx
python -m pipx ensurepath

# Install gira
pipx install gira

2. Development Installation (From Source)¶

Clone and Install¶

# Clone the repository
git clone https://github.com/goatbytes/gira.git
cd gira

# Install in editable mode with development dependencies
pip install -e ".[dev]"

Using the Setup Script¶

# Run the automated setup script
./setup.sh

The setup script automatically: - Verifies Python version compatibility - Installs all dependencies in development mode - Configures Git commit templates - Sets up shell completions - Runs initial tests and coverage checks

3. Container/Docker Installation¶

Note: Docker support is planned for future releases. Currently, standard installation is recommended.

4. Platform-Specific Instructions¶

macOS¶

# Using pip
pip3 install gira

Note: Homebrew support is planned for future releases.

Windows¶

# Using pip
py -m pip install gira

# Using pipx
py -m pip install pipx
py -m pipx ensurepath
pipx install gira

Linux¶

# Ubuntu/Debian
sudo apt update
sudo apt install python3-pip
pip3 install gira

# Fedora
sudo dnf install python3-pip
pip3 install gira

# Arch Linux
sudo pacman -S python-pip
pip install gira

🔧 Post-Installation Setup¶

1. Verify Installation¶

# Check version
gira --version

# View help
gira --help

# Test basic functionality
gira init

2. Shell Completions¶

Gira provides two methods for shell completions:

Method 1: Using the completion command (Deprecated)¶

⚠️ DEPRECATION WARNING: The custom completion system is deprecated. Use Method 2 (Typer's built-in completion) for better integration and automatic ID completion.

For reference only (deprecated):¶

# For bash (deprecated)
gira completion install bash

# For zsh (deprecated) 
gira completion install zsh

# For fish (deprecated)
gira completion install fish

Method 2: Using Typer's built-in completion (Recommended)¶

Install completion automatically:¶

# This works for all shells (bash, zsh, fish, powershell)
gira --install-completion

Manual installation by shell:¶

Bash:

# Add to ~/.bashrc
eval "$(_GIRA_COMPLETE=bash_source gira)"

Zsh:

# Add to ~/.zshrc
eval "$(_GIRA_COMPLETE=zsh_source gira)"

Fish:

# Add to ~/.config/fish/config.fish
_GIRA_COMPLETE=fish_source gira | source

PowerShell:

# Add to $PROFILE
(& gira --install-completion powershell) | Out-String | Invoke-Expression

Completion Features¶

The shell completions provide: - Command and subcommand suggestions - Option flag completion - Dynamic ticket/epic ID completion - File path completion for attachment commands - Storage provider name completion - Attachment filename completion for download/remove operations

3. Configure Git Integration¶

# Set up commit message template
git config --local commit.template .gitmessage

# Enable commit message validation
chmod +x .gira/scripts/validate-commit.sh

4. Editor Configuration¶

VS Code¶

Install the "Gira" extension (when available) or configure tasks:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Gira Board",
      "type": "shell",
      "command": "gira board",
      "group": "build"
    }
  ]
}

Vim/Neovim¶

Add to your configuration:

" Quick commands for Gira
command! GiraBoard !gira board
command! GiraTickets !gira ticket list

🐛 Troubleshooting¶

Common Issues¶

Python Version Error¶

ERROR: Python 3.8 or higher is required

Solution: Upgrade Python or use pyenv to manage versions:

# Using pyenv
pyenv install 3.12.0
pyenv local 3.12.0

Permission Denied¶

ERROR: Permission denied when installing

Solution: Use user installation or virtual environment:

# User installation
pip install --user gira

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install gira

Import Errors¶

ERROR: No module named 'gira'

Solution: Ensure pip installation completed and PATH is configured:

# Check installation
pip show gira

# Verify PATH
echo $PATH  # Should include pip's bin directory

Git Not Found¶

ERROR: Git command not found

Solution: Install Git for your platform: - macOS: brew install git - Ubuntu: sudo apt install git - Windows: Download from https://git-scm.com

Getting Help¶

If you encounter issues:

Search existing issues
Create a new issue with:
Python version: python --version
Gira version: gira --version
Error message and traceback
Steps to reproduce

🔄 Upgrading¶

Upgrade to Latest Version¶

# Using pip
pip install --upgrade gira

# Using pipx
pipx upgrade gira

Upgrade from Source¶

cd gira
git pull origin main
pip install -e ".[dev]" --upgrade

🗑️ Uninstallation¶

Remove Gira¶

# Using pip
pip uninstall gira

# Using pipx
pipx uninstall gira

# Clean up configuration
rm -rf ~/.config/gira  # User config
rm -rf .gira          # Project data

📚 Next Steps¶

After installation:

Initialize a project: gira init "My Project"
Read the quickstart: See Quickstart Guide
Explore commands: Run gira --help
Set up AI integration: Run gira ai setup

📝 License¶

Gira is released under the MIT License. See LICENSE for details.