Quickstart Guide¶

Get up and running with Gira in under 5 minutes! This guide walks you through the essential commands and workflows.

🎯 What is Gira?¶

Gira is a Git-native project management tool that stores all project data as JSON files in your repository. It's designed for developers who want to:

Track issues alongside code
Version control project management data
Enable AI agents to help manage projects
Work offline with full functionality
Integrate project management into their Git workflow

🚀 Installation¶

# Install from PyPI
pip install gira

# Or install from source
git clone https://github.com/goatbytes/gira.git
cd gira
pip install -e ".[dev]"

# Verify installation
gira --version

📋 Basic Workflow¶

1. Initialize Your Project¶

# In your Git repository
cd your-project
gira init "Your Project Name"

# This creates:
# .gira/
#   ├── config.json      # Project configuration
#   ├── board/           # Kanban board structure
#   ├── epics/           # Epic definitions
#   ├── sprints/         # Sprint data
#   └── comments/        # Ticket comments

2. Create Your First Ticket¶

# Create a feature ticket
gira ticket create "Add user authentication" --type feature --priority high

# Output:
# ✅ Created ticket GCM-1: Add user authentication

3. View Your Board¶

gira board

# Output:
# ┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
# ┃ TODO (1)        ┃ IN PROGRESS (0) ┃ REVIEW (0)      ┃ DONE (0)        ┃
# ┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
# │ GCM-1 [HIGH]    │                 │                 │                 │
# │ Add user        │                 │                 │                 │
# │ authentication  │                 │                 │                 │
# └─────────────────┴─────────────────┴─────────────────┴─────────────────┘

4. Work on a Ticket¶

# Move ticket to in-progress
gira ticket move GCM-1 "in progress"

# Add a comment with progress
gira comment add GCM-1
# (Opens your editor to write a detailed comment)

# Comment methods (similar to descriptions)
gira comment add GCM-1                    # Opens editor
echo "Quick update" | gira comment add GCM-1 --from-stdin  # From stdin

# View ticket details
gira ticket show GCM-1

5. Complete Your Work¶

# Move to review when ready
gira ticket move GCM-1 review

# After code review, move to done
gira ticket move GCM-1 done

# Commit with ticket reference
git commit -m "feat(GCM-1): implement user authentication

- Add login/logout endpoints
- Implement JWT token validation
- Add user session management

Gira: GCM-1"

🎮 Essential Commands¶

Ticket Management¶

# List all tickets
gira ticket list

# Filter tickets
gira ticket list --status "in progress"
gira ticket list --priority high
gira ticket list --type bug

# Search tickets using the query system
gira query 'title contains "authentication"'

# Update ticket details
gira ticket update GCM-1 --priority medium --description "Updated requirements"

# Add labels
gira ticket update GCM-1 --add-label backend --add-label security

# Multi-line descriptions
gira ticket create "Complex feature" --description editor  # Opens your editor
gira ticket update GCM-1 --description editor              # Edit existing description
echo "Multi-line text" | gira ticket create "Task" --description -  # Read from stdin

Epic Management¶

# Create an epic
gira epic create "User Management System" --description "Complete user auth and profile features"

# Create epic with detailed description using editor
gira epic create "Complex System" --description editor

# Add tickets to epic
gira epic update EPIC-001 --add-ticket GCM-1 --add-ticket GCM-2

# Update epic description with editor
gira epic update EPIC-001 --description editor

# View epic progress
gira epic show EPIC-001

# List all epics
gira epic list

Sprint Management¶

# Create a 2-week sprint
gira sprint create "Sprint 1" 14

# Add tickets to sprint
gira sprint update --add-ticket GCM-1 --add-ticket GCM-2

# View sprint progress
gira sprint show

# Start/complete sprint
gira sprint start
gira sprint complete

📝 Real-World Example¶

Let's walk through a complete feature implementation:

Step 1: Create Epic and Tickets¶

# Create an epic for the feature
gira epic create "API Authentication" --description "Implement secure API authentication system"

# Create related tickets
gira ticket create "Design authentication schema" --type task --epic EPIC-001
gira ticket create "Implement JWT tokens" --type feature --epic EPIC-001 --priority high
gira ticket create "Add login endpoint" --type feature --epic EPIC-001
gira ticket create "Add middleware for auth" --type feature --epic EPIC-001
gira ticket create "Write auth tests" --type task --epic EPIC-001

Step 2: Create Sprint and Add Tickets¶

# Create a sprint
gira sprint create "Auth Sprint" 14

# Add high-priority tickets
gira sprint update --add-ticket GCM-2 --add-ticket GCM-3

# Start the sprint
gira sprint start

Step 3: Work Through Tickets¶

# Start with design task
gira ticket move GCM-1 "in progress"

# Add implementation notes
gira comment add GCM-1
# Write: "Decided on JWT with refresh tokens. 
# Access tokens expire in 15 minutes, refresh tokens in 7 days."

# Complete and move to next ticket
gira ticket move GCM-1 done
gira ticket move GCM-2 "in progress"

Step 4: Track Progress¶

# Check sprint status
gira sprint show

# View epic progress
gira epic show EPIC-001

# See the board
gira board

🔥 Pro Tips¶

1. Multi-line Input Methods¶

Gira supports three ways to input multi-line text for descriptions:

# Method 1: Use your preferred editor (respects $EDITOR)
gira ticket create "Feature with detailed spec" --description editor

# Method 2: Read from stdin
cat design-doc.md | gira ticket create "Implementation task" --description -

# Method 3: Use a here-doc
gira ticket create "Bug report" --description - << EOF
Steps to reproduce:
1. Open the application
2. Click on settings
3. Error appears

Expected: Settings page opens
Actual: Application crashes
EOF

When using the editor: - Lines starting with # are treated as comments and ignored - The editor pre-populates with existing content for updates - Exit without saving to cancel the operation

2. Use Aliases for Speed¶

Add to your shell configuration:

alias gb="gira board"
alias gt="gira ticket"
alias ge="gira epic"
alias gs="gira sprint"

# Usage:
gb                    # View board
gt create "Fix bug"   # Create ticket
gt move GCM-1 done    # Move ticket

2. Integrate with Git Hooks¶

Create .git/hooks/prepare-commit-msg:

#!/bin/bash
# Auto-add Gira ticket from branch name
BRANCH=$(git branch --show-current)
TICKET=$(echo $BRANCH | grep -oE 'GCM-[0-9]+')

if [ ! -z "$TICKET" ]; then
    echo -e "\n\nGira: $TICKET" >> $1
fi

3. Use Templates¶

Create .gira/templates/bug.md:

## Bug Description
[Clear description of the bug]

## Steps to Reproduce
1. 
2. 
3. 

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- OS: 
- Version:

4. Quick Status Updates¶

# Bulk move completed tickets
gira ticket list --status review | grep GCM | cut -d' ' -f1 | xargs -I {} gira ticket move {} done

# Find stale tickets
gira ticket list --status "in progress" --format json | jq '.[] | select(.updated_at < (now - 604800))'

🎯 Common Workflows¶

Daily Standup¶

# What I worked on yesterday (use query system)
gira query 'updated_at > days_ago(1) AND comment_count > 0'

# What I'm working on today
gira ticket list --status "in progress" --assignee "$(git config user.email)"

# Blockers (using labels)
gira ticket list --label blocked

Code Review Process¶

# Move to review with PR link
gira ticket update GCM-1 --add-label "pr-ready"
gira ticket move GCM-1 review
gira comment add GCM-1  # Add PR link in comment

# After approval
gira ticket move GCM-1 done
git commit -m "feat(GCM-1): implement feature"

Release Planning¶

# View all tickets for release
gira epic show EPIC-001

# Check completion status
gira ticket list --epic EPIC-001 --status done | wc -l
gira ticket list --epic EPIC-001 --status "!done" | wc -l

# Generate release notes
gira ticket list --status done --since "2 weeks ago" --format markdown > RELEASE_NOTES.md

🔗 Integration Examples¶

CI/CD Integration¶

# .github/workflows/gira.yml
name: Update Gira Tickets
on:
  pull_request:
    types: [opened, closed]

jobs:
  update-tickets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Extract ticket ID
        id: ticket
        run: echo "TICKET=$(echo ${{ github.head_ref }} | grep -oE 'GCM-[0-9]+')" >> $GITHUB_OUTPUT
      - name: Update ticket status
        if: steps.ticket.outputs.TICKET
        run: |
          if [ "${{ github.event.action }}" = "opened" ]; then
            gira ticket move ${{ steps.ticket.outputs.TICKET }} review
          elif [ "${{ github.event.action }}" = "closed" ] && [ "${{ github.event.pull_request.merged }}" = "true" ]; then
            gira ticket move ${{ steps.ticket.outputs.TICKET }} done
          fi

Pre-commit Hook¶

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: gira-ticket-check
        name: Check Gira ticket in commit
        entry: .gira/scripts/validate-commit.sh
        language: script
        stages: [commit-msg]

📚 Next Steps¶

Now that you've mastered the basics:

Explore advanced features: See User Guide
Set up AI integration: Run gira ai setup and see AI Agents Guide
Learn integrations: Check Integrations Guide
Contribute: See Contributing Guide

🆘 Getting Help¶

Command help: gira [command] --help
Documentation: Full documentation
Issues: GitHub Issues
Community: Discussions

Happy project management with Gira! 🎉