> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wit.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository

> Repository class API reference

The `Repository` class is the main entry point for all repository operations.

## Import

```typescript theme={null}
import { Repository } from 'wit';
```

## Static Methods

### Repository.init()

Create a new repository.

```typescript theme={null}
static init(path?: string): Repository
```

**Parameters:**

| Name   | Type     | Description                                          |
| ------ | -------- | ---------------------------------------------------- |
| `path` | `string` | Directory to initialize (default: current directory) |

**Returns:** `Repository` instance

**Example:**

```typescript theme={null}
// Initialize in current directory
const repo = Repository.init();

// Initialize in specific path
const repo = Repository.init('/path/to/project');
```

***

### Repository.open()

Open an existing repository.

```typescript theme={null}
static open(path?: string): Repository
```

**Parameters:**

| Name   | Type     | Description                                  |
| ------ | -------- | -------------------------------------------- |
| `path` | `string` | Repository path (default: current directory) |

**Returns:** `Repository` instance

**Throws:** `NotFoundError` if no repository found

**Example:**

```typescript theme={null}
const repo = Repository.open('/path/to/repo');
```

***

### Repository.isRepository()

Check if a directory is a wit repository.

```typescript theme={null}
static isRepository(path: string): boolean
```

**Example:**

```typescript theme={null}
if (Repository.isRepository('/some/path')) {
  const repo = Repository.open('/some/path');
}
```

## Instance Methods

### Staging

#### add()

Stage files for commit.

```typescript theme={null}
add(path: string | string[]): void
```

**Parameters:**

| Name   | Type                 | Description      |
| ------ | -------------------- | ---------------- |
| `path` | `string \| string[]` | File(s) to stage |

**Example:**

```typescript theme={null}
repo.add('file.ts');
repo.add(['file1.ts', 'file2.ts']);
repo.add('.');  // Stage all
```

***

#### unstage()

Remove files from staging area.

```typescript theme={null}
unstage(path: string | string[]): void
```

**Example:**

```typescript theme={null}
repo.unstage('file.ts');
```

***

### Committing

#### commit()

Create a new commit.

```typescript theme={null}
commit(message: string, options?: CommitOptions): string
```

**Parameters:**

| Name      | Type            | Description       |
| --------- | --------------- | ----------------- |
| `message` | `string`        | Commit message    |
| `options` | `CommitOptions` | Optional settings |

**Options:**

```typescript theme={null}
interface CommitOptions {
  all?: boolean;      // Stage all tracked files
  amend?: boolean;    // Amend last commit
  author?: string;    // Override author
  email?: string;     // Override email
}
```

**Returns:** Commit hash

**Example:**

```typescript theme={null}
const hash = repo.commit('Add feature');

// Stage all and commit
const hash = repo.commit('Update', { all: true });

// Amend last commit
repo.commit('Fixed message', { amend: true });
```

***

### Status

#### status()

Get repository status.

```typescript theme={null}
status(): Status
```

**Returns:**

```typescript theme={null}
interface Status {
  branch: string;
  staged: FileStatus[];
  modified: FileStatus[];
  untracked: string[];
  ahead: number;
  behind: number;
}
```

**Example:**

```typescript theme={null}
const status = repo.status();

console.log('On branch:', status.branch);
console.log('Staged files:', status.staged.length);
console.log('Modified files:', status.modified.length);
console.log('Untracked:', status.untracked);
```

***

### History

#### log()

Get commit history.

```typescript theme={null}
log(options?: LogOptions): Commit[]
```

**Options:**

```typescript theme={null}
interface LogOptions {
  limit?: number;     // Max commits to return
  since?: Date;       // Commits after this date
  until?: Date;       // Commits before this date
  author?: string;    // Filter by author
  path?: string;      // Filter by path
}
```

**Example:**

```typescript theme={null}
// All commits
const commits = repo.log();

// Last 10 commits
const recent = repo.log({ limit: 10 });

// Commits affecting a file
const fileHistory = repo.log({ path: 'src/index.ts' });
```

***

#### getCommit()

Get a specific commit.

```typescript theme={null}
getCommit(ref: string): Commit
```

**Parameters:**

| Name  | Type     | Description              |
| ----- | -------- | ------------------------ |
| `ref` | `string` | Commit hash or reference |

**Example:**

```typescript theme={null}
const commit = repo.getCommit('abc123');
const head = repo.getCommit('HEAD');
const parent = repo.getCommit('HEAD~1');
```

***

### Diffing

#### diff()

Get differences.

```typescript theme={null}
diff(options?: DiffOptions): DiffResult
```

**Options:**

```typescript theme={null}
interface DiffOptions {
  staged?: boolean;   // Diff staged vs HEAD
  from?: string;      // Start commit/ref
  to?: string;        // End commit/ref
  path?: string;      // Limit to path
}
```

**Example:**

```typescript theme={null}
// Unstaged changes
const unstaged = repo.diff();

// Staged changes
const staged = repo.diff({ staged: true });

// Between commits
const changes = repo.diff({ from: 'abc', to: 'def' });
```

***

### Branches

#### branches()

List all branches.

```typescript theme={null}
branches(): Branch[]
```

**Returns:**

```typescript theme={null}
interface Branch {
  name: string;
  hash: string;
  current: boolean;
  upstream?: string;
}
```

**Example:**

```typescript theme={null}
const branches = repo.branches();
for (const branch of branches) {
  console.log(branch.current ? '* ' : '  ', branch.name);
}
```

***

#### currentBranch()

Get current branch name.

```typescript theme={null}
currentBranch(): string | null
```

Returns `null` if in detached HEAD state.

***

#### createBranch()

Create a new branch.

```typescript theme={null}
createBranch(name: string, startPoint?: string): void
```

**Example:**

```typescript theme={null}
repo.createBranch('feature');
repo.createBranch('from-tag', 'v1.0.0');
```

***

#### deleteBranch()

Delete a branch.

```typescript theme={null}
deleteBranch(name: string, force?: boolean): void
```

***

#### switch()

Switch to a branch.

```typescript theme={null}
switch(branch: string, options?: SwitchOptions): void
```

**Options:**

```typescript theme={null}
interface SwitchOptions {
  create?: boolean;   // Create branch if doesn't exist
}
```

**Example:**

```typescript theme={null}
repo.switch('main');
repo.switch('new-feature', { create: true });
```

***

### Merging

#### merge()

Merge a branch.

```typescript theme={null}
merge(branch: string, options?: MergeOptions): MergeResult
```

**Returns:**

```typescript theme={null}
interface MergeResult {
  success: boolean;
  hash?: string;           // Merge commit hash
  conflicts?: string[];    // Conflicting files
}
```

**Example:**

```typescript theme={null}
const result = repo.merge('feature');
if (!result.success) {
  console.log('Conflicts in:', result.conflicts);
}
```

***

### Undo

#### undo()

Undo operations.

```typescript theme={null}
undo(options?: UndoOptions): void
```

**Options:**

```typescript theme={null}
interface UndoOptions {
  steps?: number;    // Number of operations to undo
}
```

**Example:**

```typescript theme={null}
repo.undo();
repo.undo({ steps: 3 });
```

***

#### restore()

Restore file from index or commit.

```typescript theme={null}
restore(path: string, options?: RestoreOptions): void
```

**Options:**

```typescript theme={null}
interface RestoreOptions {
  staged?: boolean;    // Unstage file
  source?: string;     // Restore from commit
}
```

***

### Low-Level Access

#### getTree()

Get a tree object.

```typescript theme={null}
getTree(hash: string): Tree
```

***

#### getBlob()

Get a blob (file content).

```typescript theme={null}
getBlob(hash: string): Blob
```

***

#### getFileContent()

Get file content from the working tree or index.

```typescript theme={null}
getFileContent(path: string, options?: { staged?: boolean }): string
```

***

## Properties

| Property     | Type      | Description                  |
| ------------ | --------- | ---------------------------- |
| `path`       | `string`  | Repository root path         |
| `witDir`     | `string`  | `.wit` directory path        |
| `workingDir` | `string`  | Working directory path       |
| `config`     | `Config`  | Repository configuration     |
| `journal`    | `Journal` | Operation journal (for undo) |

## Example: Full Workflow

```typescript theme={null}
import { Repository } from 'wit';

// Open or create repo
const repo = Repository.isRepository('.')
  ? Repository.open('.')
  : Repository.init('.');

// Make changes and stage
repo.add('src/feature.ts');
repo.add('tests/feature.test.ts');

// Check what's staged
const status = repo.status();
console.log('Staged:', status.staged.map(f => f.path));

// Review diff
const diff = repo.diff({ staged: true });
for (const file of diff.files) {
  console.log(`\n${file.path}:`);
  for (const hunk of file.hunks) {
    console.log(hunk.header);
  }
}

// Commit
const hash = repo.commit('Add new feature');
console.log('Created commit:', hash);

// View history
const commits = repo.log({ limit: 5 });
for (const commit of commits) {
  console.log(`${commit.hash.slice(0, 7)} ${commit.message}`);
}
```