# How the Codex Plugin Resolves the Workspace Root: Git Detection and Fallback Strategy

> Discover how the Codex plugin finds your workspace root using Git detection and a fallback strategy. Learn about the `git rev-parse` command and its reliable alternatives.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-12

---

**The Codex plugin resolves the workspace root by first attempting to locate the Git repository top-level via `git rev-parse --show-toplevel`, and gracefully falls back to the current working directory when Git is unavailable or the directory is not a repository.**

In the `openai/codex-plugin-cc` repository, the `resolveWorkspaceRoot` function determines which directory should serve as the project’s top-level context. This logic ensures Git-aware features work correctly while allowing the plugin to operate in non-Git environments.

## The Two-Step Resolution Strategy

The resolution process follows a simple priority: Git first, fallback second.

### Step 1: Git Repository Detection

The primary mechanism relies on Git to identify the true repository root. When `resolveWorkspaceRoot(cwd)` is called, it immediately delegates to `ensureGitRepository(cwd)` from `plugins/codex/scripts/lib/git.mjs`.

### Step 2: Current Working Directory Fallback

If Git detection fails—whether because Git is not installed, the command returns an error, or the directory is not inside a repository—the function catches the exception and returns the original `cwd` parameter. This ensures the plugin remains functional outside Git repositories.

## Core Implementation in workspace.mjs

The `resolveWorkspaceRoot` function in `plugins/codex/scripts/lib/workspace.mjs` implements a thin try-catch wrapper around the Git detection logic:

```javascript
export function resolveWorkspaceRoot(cwd) {
  try {
    // Attempt to locate the Git repository root.
    return ensureGitRepository(cwd);
  } catch {
    // If any error occurs (e.g. not a Git repo, Git missing),
    // simply fall back to the current working directory.
    return cwd;
  }
}

```

This design isolates Git-specific error handling within the `ensureGitRepository` call while keeping the workspace resolution logic clean and predictable.

## Git Detection with ensureGitRepository

The heavy lifting occurs in `plugins/codex/scripts/lib/git.mjs`, where `ensureGitRepository` executes `git rev-parse --show-toplevel` via a low-level wrapper that disables shell interpolation:

```javascript
export function ensureGitRepository(cwd) {
  const result = git(cwd, ["rev-parse", "--show-toplevel"]);
  const errorCode = result.error && "code" in result.error ? result.error.code : null;
  if (errorCode === "ENOENT") {
    throw new Error("git is not installed. Install Git and retry.");
  }
  if (result.status !== 0) {
    throw new Error("This command must run inside a Git repository.");
  }
  return result.stdout.trim();
}

```

The function returns the absolute path of the repository root. It throws specific errors for two failure modes: `ENOENT` indicates Git is not installed, while a non-zero exit status indicates the current directory is not within a Git repository.

## Practical Usage Examples

When working inside a Git repository, the resolver correctly identifies the top-level directory even when called from a subdirectory:

```javascript
import { resolveWorkspaceRoot } from "./plugins/codex/scripts/lib/workspace.mjs";

// Inside a Git repository
const cwd = "/home/user/my-project/src";
const workspaceRoot = resolveWorkspaceRoot(cwd);
console.log(workspaceRoot);
// → "/home/user/my-project"

```

When no Git repository is present, the function returns the input directory unchanged:

```javascript
// No Git repository present
const cwdNoGit = "/tmp/scratch";
const workspaceRoot2 = resolveWorkspaceRoot(cwdNoGit);
console.log(workspaceRoot2);
// → "/tmp/scratch"

```

Higher-level features like `collectReviewContext` depend on this resolution to gather repository data:

```javascript
import { collectReviewContext } from "./plugins/codex/scripts/lib/git.mjs";
import { resolveWorkspaceRoot } from "./plugins/codex/scripts/lib/workspace.mjs";

const cwd = process.cwd();
const root = resolveWorkspaceRoot(cwd);
const target = { mode: "auto" };
const context = collectReviewContext(root, target);

```

## Why This Design Matters

- **Git-aware operations**: Features like branch diffs and status checks require the true repository root to function correctly.
- **Non-Git compatibility**: The fallback to `cwd` allows the plugin to operate on plain directories without throwing hard failures.
- **Code isolation**: Centralizing Git logic in `ensureGitRepository` makes it reusable across the plugin, particularly for functions like `collectReviewContext` that need reliable repository detection.

## Summary

- The **workspace root** is resolved via `resolveWorkspaceRoot` in `plugins/codex/scripts/lib/workspace.mjs`.
- The function first attempts to locate the Git repository root using `ensureGitRepository` in `plugins/codex/scripts/lib/git.mjs`.
- If Git is unavailable or the directory is not a repository, the function **falls back to the current working directory**.
- This design supports both Git-aware features (branch diffs, status) and non-Git projects without requiring configuration changes.

## Frequently Asked Questions

### What happens if Git is not installed on the system?

The plugin checks for the `ENOENT` error code when attempting to execute Git. If Git is missing, `ensureGitRepository` throws an error, which `resolveWorkspaceRoot` catches and handles by returning the current working directory instead of failing.

### Can I use the Codex plugin outside of a Git repository?

Yes. While the plugin attempts to detect a Git repository to enable features like branch comparisons, it will gracefully fall back to treating the current directory as the workspace root if no Git repository is found, allowing operation on plain directories.

### Which Git command does the plugin use to find the repository root?

The plugin executes `git rev-parse --show-toplevel` via the `ensureGitRepository` function in `plugins/codex/scripts/lib/git.mjs`. This command returns the absolute path of the top-level directory of the current Git repository.

### How does resolveWorkspaceRoot handle nested Git repositories?

The function relies on Git's native behavior. When `git rev-parse --show-toplevel` is executed from within a nested repository, Git returns the root of that specific repository, ensuring the plugin uses the correct context for the current working directory.