How Repository References Like Branches, Tags, and Commits Are Resolved by the Instagit API

Instagit resolves branches, tags, and commits by appending the reference to the repository identifier using an @ separator, converting the combined "model string" into a specific commit SHA on the backend through standard Git resolution semantics.

The Instagit API treats a repository plus a reference as a single identifier, enabling precise code analysis at any point in history. Understanding how repository references like branches, tags, and commits are resolved by the Instagit API is essential for targeting specific versions of a codebase when using the Model Context Protocol (MCP) tools or the Node SDK.

The Model String Convention

Instagit uses a compact model string format to represent a repository at a specific point in time. The convention follows a simple repo@ref pattern:

• repo: The repository identifier (e.g., facebook/react)
• @: The separator character
• ref: An optional branch name, tag name, or commit SHA

When the ref parameter is omitted, the model string contains only the repository name, signaling the backend to use the repository's default branch.

SDK Implementation of Reference Handling

The Instagit SDK processes references through three distinct layers before transmitting them to the API.

Schema Definition in src/index.ts

The MCP ask_repo tool accepts an optional ref parameter that defaults to null. In src/index.ts, the parameter is defined using a Zod schema that allows nullable strings:

// src/index.ts
ref: z.string().nullable().optional().default(null)   // defaults to repository's default branch

This definition ensures that when users omit the reference, the system automatically targets the repository's default branch.

String Construction in src/api.ts

The buildModelString() function in src/api.ts (lines 31‑35) concatenates the repository identifier with the reference using the @ separator:

// src/api.ts
function buildModelString(repo: string, ref: string | null): string {
  let model = repo;
  if (ref) model += `@${ref}`;   // appends branch, tag, or commit SHA
  return model;
}

This function handles the conditional logic that determines whether to append the reference suffix.

Payload Transmission

The constructed model string is placed into the JSON payload sent to the /v1/responses endpoint:

// src/api.ts (payload construction)
const payload = { model, input: prompt, stream: true };

The model field now contains the fully qualified reference string (e.g., owner/[email protected]), which the Instagit service uses to locate the exact code snapshot.

Backend Git Resolution Logic

Once the Instagit API receives the model string, it performs a Git resolve step to translate the reference into a concrete commit SHA.

Repository Cloning and Caching

The service first clones the repository or reuses a cached clone to ensure it has access to the full Git object database.

Reference Resolution Semantics

The backend applies standard Git resolution rules based on the suffix provided after the @ symbol:

• Branch names → Resolve to the tip commit of that branch (e.g., main becomes the latest commit on that branch)
• Tag names → Look up the tag object and resolve to the associated commit (e.g., v20.0.0 resolves to the tagged commit)
• Commit SHA → Used directly as the target snapshot (e.g., 5e2c3a9b9f4d7e9b specifies an exact commit)
• Omitted reference → Falls back to the repository's default branch as reported by the remote (typically main or master)

After resolution, the analysis runs against the specific commit snapshot, guaranteeing that answers correspond exactly to the requested point in history.

Practical Code Examples

Targeting a Specific Branch

Analyze the main branch of the React repository:

import { analyzeRepoStreaming } from "instagit";

await analyzeRepoStreaming({
  repo: "facebook/react",
  ref: "main",                // branch name
  prompt: "Describe how the concurrent mode scheduler works.",
});

Analyzing a Tagged Release

Inspect the Node.js v20.0.0 release:

await analyzeRepoStreaming({
  repo: "nodejs/node",
  ref: "v20.0.0",             // tag
  prompt: "What changes were introduced in the HTTP/2 implementation?",
});

Pinning to a Specific Commit

Reference an exact commit SHA in the Linux kernel:

await analyzeRepoStreaming({
  repo: "torvalds/linux",
  ref: "5e2c3a9b9f4d7e9b",    // commit SHA
  prompt: "Explain the memory‑model changes in this commit.",
});

Default Branch Analysis

Omit the ref parameter to analyze the repository's default branch:

await analyzeRepoStreaming({
  repo: "vercel/next.js",
  prompt: "How does Next.js perform incremental static regeneration?",
});

All calls generate a model string sent to /v1/responses:

• facebook/react@main
• nodejs/[email protected]
• torvalds/linux@5e2c3a9b9f4d7e9b
• vercel/next.js (no suffix → default branch)

Key Source Files

File	Role
src/index.ts	Declares the ask_repo tool schema, including the optional ref field (default = null).
src/api.ts	Builds the model string (repo@ref) via buildModelString() and sends it to the /v1/responses endpoint.
src/types.ts	Defines the StreamOptions shape that the streaming function consumes (including ref).
src/kitt.ts	Handles progress tracking – not directly involved in ref resolution but part of the request lifecycle.

These files implement the end‑to‑end flow that transforms a user‑supplied reference into the concrete code snapshot analyzed by the Instagit service.

Summary

• Instagit uses a repo@ref model string format to identify specific repository states.
• The ref parameter in src/index.ts accepts branch names, tags, or commit SHAs, defaulting to null for the default branch.
• The buildModelString() function in src/api.ts concatenates the repository and reference using the @ separator.
• The backend resolves the reference using standard Git semantics, converting branches to tip commits, tags to associated commits, and using SHAs directly.
• Omitting the reference triggers analysis against the repository's default branch as reported by the remote.

Frequently Asked Questions

Can I use short commit SHAs or do they need to be full 40-character hashes?

The Instagit API accepts standard Git reference strings. While full 40-character SHAs guarantee uniqueness, the backend typically resolves short SHAs using Git's standard disambiguation rules. However, for production stability, using the full SHA or a named reference (branch/tag) is recommended to avoid collisions.

What happens if I specify a reference that does not exist in the repository?

If the backend cannot resolve the provided reference (whether a branch, tag, or commit SHA), the Git resolution step fails. The API returns an error indicating that the reference could not be found, preventing analysis against a non-existent or inaccessible state of the codebase.

Does Instagit fetch the latest changes from remote branches before resolving?

The service maintains cached clones of repositories for performance. When you request a branch reference (like main), the backend resolves to the tip commit present in the cached repository. To ensure you are analyzing the absolute latest remote state, the system may refresh the clone, but resolution always occurs against the commit reachable by that reference name at the time of the request.

Can I analyze a specific pull request using the ref parameter?

Pull requests can be accessed using their specific Git references. For most GitHub repositories, you can reference a pull request by number using the format refs/pull/NUMBER/head as the ref value, or by using the specific merge commit SHA if available. This allows analysis of the exact code state proposed in a pull request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}