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

> Learn how the Instagit API resolves repository references like branches tags and commits by appending them to the repository identifier for seamless Git integration.

- Repository: [Instalabs AI/instagit](https://github.com/instalabsai/instagit)
- Tags: internals
- Published: 2026-02-16

---

**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`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts)

The MCP `ask_repo` tool accepts an optional `ref` parameter that defaults to `null`. In **[`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts)**, the parameter is defined using a Zod schema that allows nullable strings:

```typescript
// 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`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts)

The **`buildModelString()`** function in **[`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts)** (lines 31‑35) concatenates the repository identifier with the reference using the `@` separator:

```typescript
// 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:

```typescript
// 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/repo@v1.2.3`), 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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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/node@v20.0.0`
- `torvalds/linux@5e2c3a9b9f4d7e9b`
- [`vercel/next.js`](https://github.com/instalabsAI/instagit/blob/main/vercel/next.js) (no suffix → default branch)

## Key Source Files

| File | Role |
|------|------|
| **[`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts)** | Declares the `ask_repo` tool schema, including the optional `ref` field (default = `null`). |
| **[`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts)** | Builds the model string (`repo@ref`) via `buildModelString()` and sends it to the `/v1/responses` endpoint. |
| **[`src/types.ts`](https://github.com/instalabsAI/instagit/blob/main/src/types.ts)** | Defines the `StreamOptions` shape that the streaming function consumes (including `ref`). |
| **[`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/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`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) accepts branch names, tags, or commit SHAs, defaulting to `null` for the default branch.
- The **`buildModelString()`** function in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/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.