Query Language Cookbook¶

This cookbook provides practical examples of Gira Query Language (GQL) queries for common project management scenarios.

🍳 Basic Recipes¶

Finding Your Work¶

# Everything assigned to you
gira ticket list --query "assignee:me()"

# Everything you created
gira ticket list --query "reporter:me()"

# Everything you're involved with
gira ticket list --query "assignee:me() OR reporter:me()"

# Your work that's not done
gira ticket list --query "assignee:me() AND status:!=done"

Status-Based Queries¶

# Ready to start
gira ticket list --query "status:todo"

# Work in progress
gira ticket list --query "status:in_progress"

# Needs review
gira ticket list --query "status:review"

# Recently completed
gira ticket list --query "status:done AND updated_at:>=days_ago(7)"

Priority-Based Queries¶

# Critical work
gira ticket list --query "priority:critical"

# High priority work not done
gira ticket list --query "priority:high AND status:!=done"

# Low priority backlog
gira ticket list --query "priority:low AND status:backlog"

🔥 Daily Standups¶

What did I work on yesterday?¶

# Your tickets updated yesterday
gira ticket list --query "assignee:me() AND updated_at:>=days_ago(1) AND updated_at:<today()"

# Your tickets moved to done recently
gira ticket list --query "assignee:me() AND status:done AND updated_at:>=days_ago(1)"

What am I working on today?¶

# Your active work
gira ticket list --query "assignee:me() AND status:in_progress"

# Your high priority todo items
gira ticket list --query "assignee:me() AND status:todo AND priority:high"

What's blocking me?¶

# Your blocked tickets
gira ticket list --query "assignee:me() AND blocked_by:not_empty"

# Tickets you're waiting on
gira ticket list --query "assignee:me() AND status:review"

🏃‍♂️ Sprint Management¶

Current Sprint Work¶

# All tickets in current sprint
gira ticket list --query "sprint_id:current_sprint()"

# Your current sprint work
gira ticket list --query "sprint_id:current_sprint() AND assignee:me()"

# Sprint work not started
gira ticket list --query "sprint_id:current_sprint() AND status:todo"

# Sprint work in progress
gira ticket list --query "sprint_id:current_sprint() AND status:in_progress"

Sprint Planning¶

# Unestimated tickets
gira ticket list --query "story_points:is_null AND type:!=subtask"

# Large tickets (might need breaking down)
gira ticket list --query "story_points:>=13"

# Tickets without epics
gira ticket list --query "epic_id:is_null AND type:!=subtask"

# Ready for sprint (estimated, not blocked)
gira ticket list --query "story_points:not_null AND blocked_by:empty AND status:todo"

Sprint Progress¶

# Completed this sprint
gira ticket list --query "sprint_id:current_sprint() AND status:done"

# Sprint burn-down (remaining work)
gira ticket list --query "sprint_id:current_sprint() AND status:!=done"

# Sprint risks (blocked or overdue)
gira ticket list --query "sprint_id:current_sprint() AND (blocked_by:not_empty OR due_date:<today())"

🎯 Epic Management¶

Epic Progress¶

# All tickets in an epic
gira ticket list --query "epic_id:EPIC-123"

# Epic work not started
gira ticket list --query "epic_id:EPIC-123 AND status:todo"

# Epic work in progress
gira ticket list --query "epic_id:EPIC-123 AND status:in_progress"

# Epic completion status
gira ticket list --query "epic_id:EPIC-123 AND status:done"

Epic Planning¶

# Active epics
gira epic list --query "status:active"

# Epics with no tickets
gira epic list --query "tickets:empty"

# Epics assigned to you
gira epic list --query "owner:me()"

# Epics due this month
gira epic list --query "target_date:<=end_of_month()"

🐛 Bug Management¶

Bug Triage¶

# All bugs
gira ticket list --query "type:bug"

# Critical bugs
gira ticket list --query "type:bug AND priority:critical"

# Unassigned bugs
gira ticket list --query "type:bug AND assignee:is_null"

# New bugs (last 7 days)
gira ticket list --query "type:bug AND created_at:>=days_ago(7)"

Bug Resolution¶

# Bugs in progress
gira ticket list --query "type:bug AND status:in_progress"

# Bugs ready for testing
gira ticket list --query "type:bug AND status:review"

# Fixed bugs
gira ticket list --query "type:bug AND status:done"

# Bugs assigned to you
gira ticket list --query "type:bug AND assignee:me()"

📊 Quality Assurance¶

Testing Queries¶

# Tickets ready for testing
gira ticket list --query "status:review"

# Tickets with attachments (might have test data)
gira ticket list --query "attachment_count:>0"

# Tickets with many comments (might indicate issues)
gira ticket list --query "comment_count:>=5"

# Recently updated tickets (might need retesting)
gira ticket list --query "updated_at:>=days_ago(3) AND status:review"

Quality Metrics¶

# Bug ratio: bugs vs features
gira ticket list --query "type:bug" --format json | jq length
gira ticket list --query "type:feature" --format json | jq length

# Rework: tickets moved back to todo
gira ticket list --query "status:todo AND updated_at:>=days_ago(7)"

# Velocity: tickets completed this week
gira ticket list --query "status:done AND updated_at:>=start_of_week()"

🔍 Advanced Searches¶

Text Search¶

# Search in title
gira ticket list --query "title:~'authentication'"

# Search in description
gira ticket list --query "description:contains('API')"

# Combined text search
gira ticket list --query "title:~'login' OR description:contains('user')"

# Exact title match
gira ticket list --query "title:'Fix login bug'"

Label-Based Queries¶

# Tickets with specific label
gira ticket list --query "labels:contains(urgent)"

# Tickets with multiple labels
gira ticket list --query "labels:contains(frontend) AND labels:contains(bug)"

# Tickets with no labels
gira ticket list --query "labels:empty"

# Tickets with many labels
gira ticket list --query "labels:not_empty"

Date Range Queries¶

# This week's work
gira ticket list --query "updated_at:>=start_of_week() AND updated_at:<=end_of_week()"

# This month's created tickets
gira ticket list --query "created_at:>=start_of_month()"

# Overdue tickets
gira ticket list --query "due_date:<today() AND status:!=done"

# Recently updated
gira ticket list --query "updated_at:>=days_ago(3)"

🔄 Workflow Queries¶

Code Review¶

# Ready for code review
gira ticket list --query "status:review AND type:!=bug"

# Your reviews
gira ticket list --query "status:review AND assignee:me()"

# Stale reviews (in review for >3 days)
gira ticket list --query "status:review AND updated_at:<=days_ago(3)"

Deployment Tracking¶

# Ready for deployment
gira ticket list --query "status:done AND updated_at:>=start_of_week()"

# Features completed this sprint
gira ticket list --query "type:feature AND status:done AND sprint_id:current_sprint()"

# Bug fixes ready for hotfix
gira ticket list --query "type:bug AND status:done AND priority:high"

🤝 Team Coordination¶

Team Workload¶

# Tickets assigned to team member
gira ticket list --query "assignee:john@example.com"

# Unassigned work
gira ticket list --query "assignee:is_null AND status:todo"

# Overloaded assignees (>10 tickets)
gira ticket list --query "assignee:not_null" --format json | jq 'group_by(.assignee) | map(select(length > 10))'

Dependencies¶

# Blocked tickets
gira ticket list --query "blocked_by:not_empty"

# Tickets blocking others
gira ticket list --query "blocks:not_empty"

# Dependency chains
gira ticket list --query "blocked_by:contains(GIRA-100)"

# Ready to unblock
gira ticket list --query "status:done AND blocks:not_empty"

📈 Reporting Queries¶

Velocity Metrics¶

# Completed this week
gira ticket list --query "status:done AND updated_at:>=start_of_week()"

# Completed last week
gira ticket list --query "status:done AND updated_at:>=weeks_ago(1) AND updated_at:<start_of_week()"

# Story points completed
gira ticket list --query "status:done AND story_points:not_null AND updated_at:>=start_of_week()"

Aging Reports¶

# Old tickets (>30 days)
gira ticket list --query "created_at:<=days_ago(30) AND status:!=done"

# Stale in-progress (>7 days)
gira ticket list --query "status:in_progress AND updated_at:<=days_ago(7)"

# Long-running epics
gira epic list --query "status:active AND created_at:<=days_ago(60)"

Quality Reports¶

# Bug creation rate
gira ticket list --query "type:bug AND created_at:>=days_ago(7)"

# Bug resolution rate
gira ticket list --query "type:bug AND status:done AND updated_at:>=days_ago(7)"

# Rework rate (moved back to todo)
gira ticket list --query "status:todo AND updated_at:>=days_ago(7)"

🎨 Output Formatting¶

JSON for Processing¶

# Get JSON data for further processing
gira ticket list --query "status:todo" --format json > todo_tickets.json

# Extract specific fields
gira ticket list --query "assignee:me()" --format json | jq '.[] | {id, title, status}'

# Count results
gira ticket list --query "type:bug" --format json | jq length

IDs Only¶

# Get just ticket IDs
gira ticket list --query "status:todo" --ids-only

# Use with other commands
gira ticket list --query "priority:high" --ids-only | xargs -I {} gira ticket show {}

🔧 Complex Combinations¶

Multi-Condition Queries¶

# High priority bugs assigned to you, not done
gira ticket list --query "priority:high AND type:bug AND assignee:me() AND status:!=done"

# Recent work in current sprint
gira ticket list --query "sprint_id:current_sprint() AND updated_at:>=days_ago(3)"

# Overdue high priority work
gira ticket list --query "due_date:<today() AND priority:high AND status:!=done"

Nested Conditions¶

# Bugs or critical features
gira ticket list --query "type:bug OR (type:feature AND priority:critical)"

# Your work that's either blocked or in review
gira ticket list --query "assignee:me() AND (blocked_by:not_empty OR status:review)"

# Recent updates to important work
gira ticket list --query "updated_at:>=days_ago(1) AND (priority:high OR priority:critical)"

💡 Pro Tips¶

Query Optimization¶

# Use specific fields for better performance
gira ticket list --query "status:todo" --limit 50

# Combine with sorting
gira ticket list --query "assignee:me()" --sort priority

# Use pagination for large results
gira ticket list --query "status:!=done" --limit 25 --offset 0

Saved Queries (using shell aliases)¶

# Add to your shell profile
alias my-work='gira ticket list --query "assignee:me() AND status:!=done"'
alias my-bugs='gira ticket list --query "assignee:me() AND type:bug"'
alias ready-for-review='gira ticket list --query "status:review"'
alias blocked='gira ticket list --query "blocked_by:not_empty"'

Query Building¶

# Start simple
gira ticket list --query "status:todo"

# Add conditions incrementally
gira ticket list --query "status:todo AND priority:high"

# Test with verbose output
gira ticket list --query "complex query here" --verbose

This cookbook provides patterns for most common project management scenarios. Combine these patterns and adapt them to your specific workflow and team needs.