Skip to content

Reports

📊 Section 8: Reports & Utilities

gira report

Description: Generates a summary report of current project activity and status. Offers high-level overviews for sprints, epics, ticket distribution, and backlog health.

Default Output:

  • Total tickets by status
  • Backlog size
  • Active sprints with progress %
  • Open vs closed epics
  • Swimlane utilization (e.g., how many tickets are “in-review”)

Options:

  • --sprint <SPRINT_ID> – report on one sprint
  • --epic <EPIC_ID> – report on epic progress
  • --all – include archived items
  • --json – machine-readable report

Example:

gira report --sprint SPRINT-2025-07-15

gira validate

Description: Performs a consistency and health check across all Gira data. Ensures no orphaned, corrupt, or mislinked records exist.

Checks Performed:

  • All tickets have valid metadata.json and description.md
  • Tickets linked to missing epics/sprints are flagged
  • Epics reference valid child ticket IDs
  • Comments and attachments are valid JSON
  • Directory structure matches .gira/config

Options:

  • --fix – attempt to auto-repair issues (e.g., unlink broken references)
  • --json – show validation results in structured format
  • --silent – suppress warnings unless critical

Example:

gira validate --fix

gira archive

Description: Archives completed tickets by moving them to .gira/archive/YYYY-MM/. Can be scoped by date, status, or sprint.

Behavior:

  • Updates ticket status to done (if not already)
  • Moves ticket folder from board/backlog to archive
  • Updates indices and relationships as needed

Options:

  • --month YYYY-MM – archive tickets completed in a given month
  • --sprint <SPRINT_ID> – archive tickets from a closed sprint
  • --older-than <N> – archive tickets closed N days ago
  • --dry-run – preview which tickets will be archived
  • --json – report archived items

Example:

gira archive --month 2025-06

gira search <query>

Description: Searches across ticket titles, descriptions, comments, and metadata for keywords or expressions.

Supports:

  • Full-text search
  • Metadata filters (e.g. assignee:alice status:todo)
  • Fuzzy match (optional)
  • Phrase queries ("setup CI/CD")

Options:

  • --comments – include comment body in search
  • --json – structured results
  • --limit N – max number of results

Example:

gira search "timeout error"
gira search status:done assignee:bob

gira stats

Description: Outputs raw project metrics for dashboards, analytics, or AI agents.

Includes:

  • Total ticket count
  • Tickets per priority, status, swimlane
  • Epic and sprint counts
  • Average ticket age
  • Lead time and cycle time (if timestamps are available)

Options:

  • --json – machine-friendly output
  • --since <YYYY-MM-DD> – only consider tickets updated since date
  • --top <N> – top assignees or labels by activity

Example:

gira stats --since 2025-07-01 --top 5