Skip to main content

​
Output Schemas

Gitquarry supports pretty, json, toon, compact, and csv. This page documents the structured formats. --format toon serializes the same data model as JSON using Token-Oriented Object Notation, so the field contracts below apply to both JSON and TOON.

​
Search JSON Shape

gitquarry search --format json serializes this top-level shape: 
{
  "host": "github.com",
  "mode": "native",
  "rank": "native",
  "query": "rust cli",
  "compiled_query": "rust cli language:rust",
  "limit": 10,
  "total_count": 123,
  "items": []
}
Each item uses the repository schema: 
{
  "name": "gitquarry",
  "full_name": "Microck/gitquarry",
  "html_url": "https://github.com/Microck/gitquarry",
  "description": "A terminal CLI for public GitHub repository search.",
  "stargazers_count": 123,
  "forks_count": 7,
  "language": "Rust",
  "topics": ["github", "search", "cli"],
  "license": {
    "key": "mit",
    "name": "MIT License",
    "spdx_id": "MIT"
  },
  "created_at": "2026-04-01T00:00:00Z",
  "updated_at": "2026-04-22T00:00:00Z",
  "pushed_at": "2026-04-22T00:00:00Z",
  "archived": false,
  "is_template": false,
  "fork": false,
  "open_issues_count": 0,
  "owner": {
    "login": "Microck"
  },
  "readme": null,
  "latest_release": null,
  "contributor_count": null,
  "explain": null,
  "probe": null
}
When probe flags are active, repository.probe can include: 
{
  "reference": "main",
  "truncated": false,
  "matched_paths": [
    {
      "path": "src/lib.rs",
      "kind": "Blob",
      "size": 1234
    }
  ],
  "searched_files": 1,
  "skipped_files": 0,
  "total_code_matches": 1,
  "code_matches": [
    {
      "path": "src/lib.rs",
      "line": 12,
      "lines": [
        {
          "line": 12,
          "text": "use octocrab::Octocrab;",
          "matched": true
        }
      ]
    }
  ]
}

​
Search Plan JSON Shape

gitquarry search --plan --format json serializes this shape and does not call GitHub: 
{
  "host": "github.com",
  "plan": {
    "query": "rust cli",
    "compiled_query": "rust cli language:rust",
    "mode": "native",
    "rank": "native",
    "sort": "stars",
    "depth": "balanced",
    "format": "json",
    "limit": 10,
    "readme": false,
    "explain": false,
    "weights": {
      "query": 1.0,
      "activity": 1.0,
      "quality": 1.0
    },
    "concurrency": 1,
    "progress": "auto",
    "post_filters": {
      "updated_after": null,
      "updated_before": null
    },
    "native_query_present": true
  },
  "network": {
    "will_call_github": false,
    "estimated_requests_if_run": 1
  }
}

​
Inspect JSON Shape

gitquarry inspect --format json wraps one repository: 
{
  "host": "github.com",
  "repository": {
    "...": "same repository schema as search items"
  }
}

​
Compare JSON Shape

gitquarry compare --format json serializes this top-level shape: 
{
  "host": "github.com",
  "total_count": 1,
  "items": [
    {
      "repository": {
        "...": "same repository schema as search items"
      },
      "tree_summary": {
        "reference": "main",
        "truncated": false,
        "total_entries": 10,
        "blobs": 7,
        "trees": 3,
        "commits": 0
      }
    }
  ]
}
tree_summary is null unless --tree-summary is active.

​
Tree JSON Shape

gitquarry tree --format json serializes this top-level shape: 
{
  "host": "github.com",
  "repository": "Microck/gitquarry",
  "reference": "main",
  "truncated": false,
  "total_count": 3,
  "items": [
    {
      "path": "src/main.rs",
      "kind": "Blob",
      "size": 1234
    }
  ]
}
kind is one of Blob, Tree, or Commit.

​
Code JSON Shape

gitquarry code --format json serializes this top-level shape: 
{
  "host": "github.com",
  "repository": "Microck/gitquarry",
  "reference": "main",
  "pattern": "fn main",
  "mode": "literal",
  "searched_files": 1,
  "skipped_files": 0,
  "total_count": 1,
  "items": [
    {
      "path": "src/main.rs",
      "line": 3,
      "lines": [
        {
          "line": 3,
          "text": "fn main() {",
          "matched": true
        }
      ]
    }
  ]
}

​
Explain Object

When --explain is active in enhanced flows, repository.explain can include: 
{
  "query": 0.82,
  "activity": 0.61,
  "quality": 0.74,
  "blended": 0.73,
  "weights": {
    "query": 1.0,
    "activity": 1.0,
    "quality": 1.0
  },
  "matched_surfaces": ["name", "description", "topics"]
}

​
CSV Columns

search and inspect CSV output write this header: 
full_name,html_url,description,stars,forks,language,topics,license,created_at,updated_at,pushed_at,archived,template,fork,open_issues_count,contributor_count,query_score,activity_score,quality_score,blended_score
Notes:
  • topics is pipe-delimited inside one CSV field
  • timestamps are RFC3339 in CSV
  • score columns are 0 when no explain data is present
  • inspect --format csv writes one row
  • tree --format csv writes path,type,size
  • code --format csv writes path,line,text
  • compare --format csv writes repository columns plus tree summary columns

​
Pretty Output

Pretty output is for humans, not strict parsing. search --format pretty prints:
  • total count
  • effective mode
  • effective rank
  • host
  • per-repo summary blocks
inspect --format pretty prints:
  • full name
  • URL
  • description
  • stars, forks, language, topics, license
  • dates
  • archived/template/fork status
  • open issue count
  • latest release when available
  • README block when requested
tree --format pretty prints repository/ref metadata and an indented file tree. code --format pretty prints match counts, file paths, line numbers, and requested context lines.