Advanced Features¶

Gira provides powerful commands that aggregate information and provide intelligent insights about your project. These features help you understand complex relationships, workflow states, and full context without running multiple commands.

Context Command¶

The gira context command provides a comprehensive view of a ticket including all related information in one place.

Overview¶

Instead of running multiple commands to understand a ticket's full situation, use context to see: - Ticket details and metadata - Epic membership - Sprint assignment - Parent/child relationships - Blocking dependencies - All comments and discussions - Related tickets

Basic Usage¶

# Show full context for a ticket
gira context GCM-123

Output Options¶

# Get JSON output for integration with other tools
gira context GCM-123 --format json

# Exclude specific information
gira context GCM-123 --no-comments --no-dependencies

By default, the context command fetches one level of related tickets. You can adjust this:

# Fetch two levels of related tickets
gira context GCM-123 --related-depth 2

# Don't fetch any related ticket details
gira context GCM-123 --related-depth 0

Example Output¶

╭─────────────────────────────── Ticket Context ───────────────────────────────╮
│ GCM-123 - Implement user authentication                                      │
│                                                                              │
│ Status: In Progress                                                          │
│ Priority: High                                                               │
│ Type: Feature                                                                │
│ Assignee: john@example.com                                                   │
│                                                                              │
│ Epic: EPIC-001 - Security Features                                          │
│ Sprint: SPRINT-2025-07 - Security Sprint                                    │
│                                                                              │
│ Blocked by:                                                                  │
│   • GCM-122 - Set up database schema                                        │
│                                                                              │
│ Children:                                                                    │
│   • GCM-124 - Add login form                                               │
│   • GCM-125 - Implement JWT tokens                                         │
│                                                                              │
│ Comments (3):                                                               │
│   ...                                                                       │
╰──────────────────────────────────────────────────────────────────────────────╯

Workflow Command¶

The gira workflow command shows available transitions for a ticket and validates if specific moves are possible.

Overview¶

Understanding what status transitions are available helps prevent invalid moves and shows what's blocking progress: - Available transitions from current status - Validation rules for each transition - Blocking conditions - Required fields

Basic Usage¶

# Show available transitions
gira workflow GCM-123

Checking Specific Transitions¶

# Check if ticket can move to review
gira workflow GCM-123 --check --to review

# See why a transition is blocked
gira workflow GCM-123 --show-reasons

Example Output¶

╭────────────────────────── Workflow Transitions ──────────────────────────╮
│ Current Status: in_progress                                               │
│                                                                           │
│ Available Transitions:                                                    │
│   → review     ✓ Ready                                                   │
│   → todo       ✓ Ready                                                   │
│   → done       ✗ Blocked                                                 │
│                                                                           │
│ Blocked Transitions:                                                      │
│   → done:                                                                │
│     - Must pass through review status first                              │
│     - Has unresolved blockers: GCM-122                                  │
╰───────────────────────────────────────────────────────────────────────────╯

JSON Output for Automation¶

gira workflow GCM-123 --format json

Returns structured data about transitions, validation rules, and blocking conditions.

Graph Command¶

The gira graph command visualizes ticket relationships as an interactive tree or structured JSON.

Overview¶

Complex projects often have intricate relationships between tickets. The graph command helps you: - Visualize blocking dependencies - Understand parent/child hierarchies - See epic membership - Trace relationship chains

Basic Usage¶

# Show relationship graph
gira graph GCM-123

Controlling Display¶

# Show only blocking relationships
gira graph GCM-123 --no-parent --no-children --no-epic

# Show only hierarchy (no dependencies)
gira graph GCM-123 --no-blockers --no-blocks

# Increase traversal depth
gira graph GCM-123 --depth 3

Example Tree Output¶

GCM-123 Implement user authentication [in_progress]
├─ Epic: EPIC-001 - Security Features
├─ Blocked by:
│  └─ GCM-122 Set up database schema [done]
├─ Blocks:
│  └─ GCM-126 Deploy to production [todo]
└─ Children:
   ├─ GCM-124 Add login form [done]
   └─ GCM-125 Implement JWT tokens [in_progress]

JSON Output for Visualization¶

gira graph GCM-123 --format json > graph.json

The JSON output can be used with graph visualization tools or custom scripts.

Export Command¶

The gira export command allows you to export your project data in various formats for backup, analysis, or integration with other tools.

JSON Export¶

Export all tickets to JSON format for processing with external tools:

# Export all active tickets
gira export json

# Export to a file
gira export json --output tickets.json

# Include archived tickets
gira export json --include-archived

# Pretty-print for readability
gira export json --pretty > readable-tickets.json

# Export specific fields only
gira export json --fields id,title,status,priority

Markdown Export¶

Create a Markdown table for easy inclusion in release notes or documentation:

# Export all tickets
gira export md

# Save to a file
gira export md --output tickets.md

# Include archived tickets
gira export md --include-archived

# Export selected fields
gira export md --fields id,title,status,priority

Use Cases for Export¶

Backup and Recovery

# Create a daily backup
gira export json --include-archived -o backup-$(date +%Y%m%d).json

Data Analysis

# Export and analyze with jq
gira export json | jq '[.[] | select(.priority == "high")] | length'

# Find overdue tickets
gira export json | jq '.[] | select(.due_date < now)'

Integration with Other Tools

# Export for spreadsheet analysis
gira export json --fields id,title,status,assignee,story_points > sprint-data.json

# Convert to CSV with jq
gira export json | jq -r '.[] | [.id, .title, .status] | @csv' > tickets.csv

Migration and Import

# Export from one project
cd ~/project-a
gira export json --include-archived -o project-a-tickets.json

# Process and import to another system
cat project-a-tickets.json | transform-script | import-tool

Features¶

Automatic Deduplication: Handles tickets that may exist in both flat and hashed storage structures
Consistent Ordering: Tickets are always sorted by ID for predictable output
Field Filtering: Export only the fields you need to reduce file size
Special Character Handling: Properly escapes all special characters in JSON

Use Cases¶

1. Daily Standup Preparation¶

# See full context for tickets you're working on
gira ticket list --mine --status in_progress | while read id; do
  gira context $id
done

2. Unblocking Work¶

# Find what's blocking your ticket
gira workflow GCM-123 --show-reasons

# Visualize the blocking chain
gira graph GCM-123 --depth 3 --no-children --no-epic

3. Epic Progress Analysis¶

# Get all tickets in an epic with their relationships
gira epic show EPIC-001 --tickets | while read id; do
  gira graph $id --format json
done > epic-graph.json

4. Sprint Planning¶

# Check which tickets are ready to move forward
gira sprint show current --tickets | while read id; do
  echo "=== $id ==="
  gira workflow $id
done

Integration Examples¶

Slack Integration¶

# Post ticket context to Slack
context=$(gira context GCM-123 --format json)
curl -X POST -H 'Content-type: application/json' \
  --data "{\"text\": \"Ticket Update\", \"attachments\": [$context]}" \
  YOUR_SLACK_WEBHOOK_URL

CI/CD Pipeline Check¶

# Ensure ticket is ready for deployment
if gira workflow GCM-123 --check --to done; then
  echo "Ticket ready for deployment"
  deploy_to_production
else
  echo "Ticket not ready"
  gira workflow GCM-123 --show-reasons
  exit 1
fi

Custom Visualization¶

import json
import subprocess
import networkx as nx
import matplotlib.pyplot as plt

# Get graph data
result = subprocess.run(['gira', 'graph', 'GCM-123', '--format', 'json'], 
                       capture_output=True, text=True)
graph_data = json.loads(result.stdout)

# Build networkx graph
G = nx.DiGraph()
# ... process graph_data to build visualization

Tips and Best Practices¶

Performance: Use --related-depth 0 with context command for faster results when you don't need related ticket details
Automation: The JSON output format is designed for easy parsing and integration with other tools
Debugging Workflows: Use workflow --show-reasons to understand why tickets are stuck
Visual Planning: Export graph data to JSON and use graph visualization tools for complex dependency analysis
Batch Operations: Combine these commands with shell scripting for powerful batch analysis

Advanced Features¶

Context Command¶

Overview¶

Basic Usage¶

Output Options¶

Controlling Related Ticket Depth¶

Example Output¶

Workflow Command¶

Overview¶

Basic Usage¶

Checking Specific Transitions¶

Example Output¶

JSON Output for Automation¶

Graph Command¶

Overview¶

Basic Usage¶

Controlling Display¶

Example Tree Output¶

JSON Output for Visualization¶

Export Command¶

JSON Export¶

Markdown Export¶

Use Cases for Export¶

Features¶

Use Cases¶

1. Daily Standup Preparation¶

2. Unblocking Work¶

3. Epic Progress Analysis¶

4. Sprint Planning¶

Integration Examples¶

Slack Integration¶

CI/CD Pipeline Check¶

Custom Visualization¶

Tips and Best Practices¶

See Also¶