---
url: /integrations/git.md
description: >-
  Git value parsers for validating branches, tags, commits, and remotes using
  isomorphic-git.
---

# Git integration

*This API is available since Optique 0.9.0.*

The *@optique/git* package provides async value parsers for validating Git
references (branches, tags, commits, remotes) using [isomorphic-git]. These
parsers validate input against an actual Git repository, ensuring that users
can only specify existing references.

```typescript twoslash
import { gitBranch, gitTag, gitCommit, gitRef, gitRemote, gitRemoteBranch } from "@optique/git";
import { option, argument } from "@optique/core/primitives";
```

[isomorphic-git]: https://isomorphic-git.org/

## Installation

::: code-group

```bash [Deno]
deno add jsr:@optique/git
```

```bash [npm]
npm add @optique/git
```

```bash [pnpm]
pnpm add @optique/git
```

```bash [Yarn]
yarn add @optique/git
```

```bash [Bun]
bun add @optique/git
```

:::

## Getting started

Import the parsers from *@optique/git* and use them with Optique primitives:

```typescript twoslash
import { gitBranch } from "@optique/git";
import { argument } from "@optique/core/primitives";

const parser = argument(gitBranch());
// Accepts: "main", "develop", "feature/my-feature"
// Rejects: "nonexistent-branch"
```

## `gitBranch()`

Validates that input matches an existing local branch name in the repository.

```typescript twoslash
import { gitBranch } from "@optique/git";
import { argument } from "@optique/core/primitives";

const branchParser = argument(gitBranch());
```

### Options

```typescript twoslash
import type { GitParserOptions } from "@optique/git";
```

### Example

```typescript twoslash
import { gitBranch } from "@optique/git";
import { option } from "@optique/core/primitives";

// Branch argument for git checkout-like command
const checkoutParser = option("-b", "--branch", gitBranch());
// Usage: myapp checkout --branch feature/my-feature
```

## `gitTag()`

Validates that input matches an existing tag name in the repository.

```typescript twoslash
import { gitTag } from "@optique/git";
import { option } from "@optique/core/primitives";

const tagParser = option("-t", "--tag", gitTag());
// Usage: myapp release --tag v1.0.0
```

### Example with custom options

```typescript twoslash
import { gitTag } from "@optique/git";
import { option } from "@optique/core/primitives";

const versionParser = option("--release", gitTag({
  metavar: "VERSION",
}));
```

## `gitRemote()`

Validates that input matches an existing remote name in the repository.

```typescript twoslash
import { gitRemote } from "@optique/git";
import { option } from "@optique/core/primitives";

const remoteParser = option("--remote", gitRemote());
// Usage: myapp fetch --remote origin
```

## `gitRemoteBranch()`

Validates that input matches an existing branch on a specific remote.

```typescript twoslash
import { gitRemoteBranch } from "@optique/git";
import { option } from "@optique/core/primitives";

const remoteBranchParser = option("--branch", gitRemoteBranch("origin"));
// Usage: myapp pull --branch main
```

### Dynamic remote with dependencies

Use the [dependency system](../concepts/dependencies.md) to validate branches
against a user-specified remote. The `gitRemoteBranch()` parser works with
async factory support in derived parsers:

```typescript twoslash
import { gitRemote, gitRemoteBranch } from "@optique/git";
import { dependency } from "@optique/core/dependency";
import { object } from "@optique/core/constructs";
import { option } from "@optique/core/primitives";

// Wrap gitRemote() as a dependency source
const remoteParser = dependency(gitRemote());

// Create a derived parser that validates branches against the selected remote
const branchParser = remoteParser.derive({
  metavar: "BRANCH",
  mode: "async",
  factory: (remote) => gitRemoteBranch(remote),
  defaultValue: () => "origin",
});

const pullCommand = object({
  remote: option("--remote", remoteParser),
  branch: option("--branch", branchParser),
});

// Now --branch validates against the remote specified by --remote:
// myapp pull --remote upstream --branch feature/new
// → validates that "feature/new" exists on "upstream"
```

Since `gitRemoteBranch()` returns an async parser, the derived parser
automatically becomes async. The dependency system handles the mode
combination seamlessly.

## `gitCommit()`

Validates that input is a valid commit SHA (full or shortened) that exists
in the repository. Returns the resolved full OID.

```typescript twoslash
import { gitCommit } from "@optique/git";
import { option } from "@optique/core/primitives";

const commitParser = option("--commit", gitCommit());
// Usage: myapp revert --commit abc1234
```

### SHA formats supported

The parser accepts various SHA formats:

* Full 40-character SHA: `d670460b4b4aece5915caf5c68d12f560a9fe3e4`
* Shortened SHAs (4+ characters): `d670460`, `d670460b4b4a`

```typescript twoslash
import { parseAsync } from "@optique/core/parser";
import { gitCommit } from "@optique/git";
import { option } from "@optique/core/primitives";

const parser = option("-c", "--commit", gitCommit());
// ---cut-before---
const result = await parseAsync(parser, ["-c", "550e840"]);
if (result.success) {
  console.log(result.value); // Full 40-char OID
}
```

## `gitRef()`

A flexible parser that accepts any valid Git reference: branches, tags, or
commits. Returns the resolved commit OID.

```typescript twoslash
import { gitRef } from "@optique/git";
import { argument } from "@optique/core/primitives";

const refParser = argument(gitRef());
// Accepts: branch names, tags, or commit SHAs
// Returns: resolved commit OID
```

## `createGitParsers()`

A factory function for creating multiple Git parsers with shared configuration.

```typescript twoslash
import { createGitParsers } from "@optique/git";
import { option } from "@optique/core/primitives";

const git = createGitParsers({
  dir: "/path/to/repo",
});

const parser = option("--branch", git.branch());
const tagParser = option("--tag", git.tag());
const commitParser = option("--commit", git.commit());
```

### Example with custom options per parser

```typescript twoslash
import { createGitParsers } from "@optique/git";

const git = createGitParsers({
  dir: "/path/to/repo",
  metavar: "REF",
});

// Override metavar for specific parser
const branchParser = git.branch({ metavar: "BRANCH_NAME" });
```

## Async mode

All Git parsers operate in async mode because they perform I/O operations
to read the Git repository:

```typescript twoslash
import { gitBranch } from "@optique/git";
import { argument } from "@optique/core/primitives";

const parser = argument(gitBranch());
// parser.mode === "async"
```

Use `parseAsync()` with async parsers:

```typescript twoslash
import { parseAsync } from "@optique/core/parser";
import { gitBranch } from "@optique/git";
import { argument } from "@optique/core/primitives";

const parser = argument(gitBranch());
// ---cut-before---
const result = await parseAsync(parser, ["main"]);
if (result.success) {
  console.log(result.value); // "main"
}
```

## Suggestions

Git parsers provide intelligent completion suggestions:

```typescript twoslash
import { gitBranch, gitTag, gitRef } from "@optique/git";
import { argument } from "@optique/core/primitives";

// Suggests existing branches
const branchParser = argument(gitBranch());
// Completing "fe" suggests: "feature/*", "fix/*", etc.

// Suggests existing tags
const tagParser = argument(gitTag());
// Completing "v1" suggests: "v1.0.0", "v1.1.0", etc.

// Suggests both branches and tags
const refParser = argument(gitRef());
// Completing "v" suggests tags; completing "fe" suggests branches
```

## Error handling

Git parsers provide clear error messages:

```bash
$ myapp --branch nonexistent
Error: Branch nonexistent does not exist. Available branches: main, develop, feature/*.

$ myapp --tag v999.0.0
Error: Tag v999.0.0 does not exist. Available tags: v1.0.0, v2.0.0.

$ myapp --commit abc
Error: Invalid commit SHA: abc. Provide an abbreviated (4+) or full (40) hexadecimal commit SHA.

$ myapp --ref nonexistent-ref
Error: Reference nonexistent-ref does not exist. Provide a valid branch, tag, or commit SHA.
```

## Custom error messages

You can customize error messages using the `errors` option with the `Message`
type from `@optique/core/message`:

```typescript twoslash
import { gitBranch } from "@optique/git";
import { message, valueSet } from "@optique/core/message";

const parser = gitBranch({
  errors: {
    notFound: (input, available) =>
      message`Branch ${input} not found. Available: ${
        valueSet(available ?? [], "none")
      }`,
    listFailed: (dir) =>
      message`Cannot read git repository at ${dir}`,
  }
});
```

### Error types

The `errors` option supports the following error types:

* `notFound(input, available?)` — Called when the git reference is not found.
  Provides the invalid input and optionally a list of available references.
* `listFailed(dir)` — Called when listing git references fails, typically
  when the directory is not a valid git repository.
* `invalidFormat(input)` — Called for commit SHA validation failures
  when the input format is invalid (e.g., too short).
* `remoteNotFound(remote, availableRemotes)` — Called by `gitRemoteBranch()`
  when the named remote does not exist.

### Example with gitCommit

```typescript twoslash
import { gitCommit } from "@optique/git";
import { message } from "@optique/core/message";

const parser = gitCommit({
  errors: {
    invalidFormat: (input) =>
      message`${input} must be 4-40 characters.`,
    notFound: (input) =>
      message`Commit ${input} not found in repository.`,
  }
});
```

### Example with createGitParsers

```typescript twoslash
import { createGitParsers } from "@optique/git";
import { message } from "@optique/core/message";

const git = createGitParsers({
  errors: {
    notFound: (input, available) =>
      message`${input} is not a valid reference.`,
  }
});

const branchParser = git.branch();
const tagParser = git.tag();
const commitParser = git.commit();
```

## Metavar defaults

Each parser uses an appropriate default metavar for help text:

| Parser              | Default metavar |
| ------------------- | --------------- |
| `gitBranch()`       | `"BRANCH"`      |
| `gitTag()`          | `"TAG"`         |
| `gitRemote()`       | `"REMOTE"`      |
| `gitRemoteBranch()` | `"BRANCH"`      |
| `gitCommit()`       | `"COMMIT"`      |
| `gitRef()`          | `"REF"`         |

Override with the `metavar` option:

```typescript twoslash
import { gitBranch, gitTag } from "@optique/git";

const branchParser = gitBranch({ metavar: "BRANCH_NAME" });
const tagParser = gitTag({ metavar: "RELEASE_VERSION" });
```

## Exported utilities

The package also re-exports several utilities from isomorphic-git for
advanced use cases:

```typescript twoslash
import { expandOid, listBranches, listTags, listRemotes, readObject, resolveRef } from "@optique/git";
```

* `expandOid()` — Expand short SHAs to full OIDs
* `listBranches()` — List all local branches
* `listTags()` — List all tags
* `listRemotes()` — List all remotes
* `readObject()` — Read a Git object
* `resolveRef()` — Resolve a ref to its OID

## Complete example

A Git-like CLI application using Git parsers:

```typescript twoslash
import { createGitParsers } from "@optique/git";
import { object, or } from "@optique/core/constructs";
import { argument, command, constant, option } from "@optique/core/primitives";
import { parseAsync } from "@optique/core/parser";

const git = createGitParsers();

const checkoutCmd = command("checkout", object({
  type: constant("checkout"),
  branch: option("-b", "--branch", git.branch()),
  startPoint: argument(git.ref()),
}));

const logCmd = command("log", object({
  type: constant("log"),
  ref: argument(git.ref()),
}));

const app = or(checkoutCmd, logCmd);
// ---cut-before---
const result = await parseAsync(app, ["checkout", "-b", "develop", "main"]);
if (result.success) {
  console.log(result.value);
}
```