1. Archive Freshness Check
Prior to running any retrieval operations, execute
gitcrawl doctor --json to verify the freshness of local archived data, guaranteeing subsequent queries rely on sufficiently up-to-date records.2. Archive Retrieval (Local-First)
Gitcrawl provides multiple local retrieval commands with no real-time GitHub API invocations required:
| Command | Function |
|---|---|
| gitcrawl threads | Bulk fetch Issue/PR threads by numerical IDs |
| gitcrawl neighbors | Retrieve adjacent threads associated with a specified Issue/PR |
| gitcrawl search | Search Issues by keywords, with filtering for open/closed status |
| gitcrawl clusters | Identify clusters of semantically similar Issues; supports sorting by cluster size and minimum size threshold filtering |
| gitcrawl cluster-detail | Inspect full detailed data of a single target cluster |
All retrieval commands support
--json formatted output for automated programmatic processing.3. PR Status Synchronization (gh-shim)
Before finalizing merge or modification decisions, Gitcrawl exposes the
gitcrawl gh subcommand to pull the latest PR runtime status:bash
gitcrawl gh pr status --compact
gitcrawl gh pr view --json
The latter outputs complete PR JSON metadata including ID, title, state, URL, draft flag, head branch and commit SHA.
Append the
--live flag to force fetching real-time live data.4. Live Validation (Native gh CLI)
Before performing any write modification operations (commenting, labeling, closing, reopening, merging, submitting PR reviews), mandatory live validation must be completed via the official native
gh command-line utility:bash
gh pr view <number> --json number,title,state,mergedAt,body,files,comments,reviews,statusCheckRollup
gh issue view <number> --json number,title,state,body,comments,closedAt
III. Core Use Cases
-
Issue/PR Triage & FilteringQuickly locate target candidates from massive batches of Issues and PRs: pull contextual data from local archives first, and invoke real-time APIs only when modification decisions need to be made.
-
Duplicate Issue Detection & ManagementLocate semantically matching Issue groups via
clustersandcluster-detailcommands to facilitate consolidation and categorized processing. -
Pre-Merge PR Status VerificationRun
gitcrawl ghto instantly check up-to-date PR attributes (merge eligibility, draft status, head branch info, etc.) before merging, preventing wrong judgements based on stale cached data. -
GitHub API Request ReductionThe local-archive-first architecture drastically cuts real-time GitHub API call volume and accelerates query speed, which delivers prominent advantages for batch processing high volumes of Issues and PRs.
IV. Standard Execution Workflow
plaintext
1. gitcrawl doctor --json → Check archive data freshness
2. gitcrawl search / threads / clusters → Retrieve candidate records from local archives
3. gitcrawl gh pr view → Fetch latest PR status (cache prioritized)
4. gitcrawl gh --live pr view → Append --live flag only when live real-time data is necessary
5. gh pr view / gh issue view → Run final live validation via native gh CLI before any write operations
6. Execute target modification actions (merge, close, label, etc.)
V. Critical Rules & Restrictions
Complete Reporting Mandate: All output results must include absolute timestamps, repository names, Issue/PR numeric IDs, cluster identifiers, and gaps in available archived data sources.
Similarity Does Not Equal Execution Basis: Cluster semantic similarity alone cannot trigger automated closing or labeling actions. Exact intent matching and live runtime validation are mandatory prerequisites.
Mandatory Live Validation Prior To Modifications: The native gh CLI must be used to cross-check live data before commenting, labeling, closing, reopening, merging, or submitting formal PR reviews.
VI. Summary
Gitcrawl is a local-first GitHub archive query and PR status synchronization utility. Its "archive-first, live-fallback" workflow maintains data accuracy while drastically boosting retrieval efficiency for Issues and PRs. It is purpose-built for developers, open-source maintainers, and automated triage pipelines that require efficient bulk processing of GitHub Issue and PR datasets.
