> ## 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.

# Advanced Commands

> Power user commands for advanced workflows

These commands provide powerful capabilities for advanced workflows.

<Note>
  For stacked diffs, see [Stacked Diffs](/features/stacked-diffs).
  For history rewriting (cherry-pick, rebase, revert), see [History Rewriting](/commands/history-rewriting).
  For remote operations, see [Remotes](/commands/remotes).
  For stash, see [Stash](/commands/stash).
  For tags, see [Tags](/commands/tags).
  For debugging (bisect, show, clean), see [Debugging](/commands/debugging).
</Note>

***

## Hooks

Customize behavior at key points in the version control workflow.

```bash theme={null}
wit hooks <command> [hook-name]
```

### Commands

| Command          | Description                  |
| ---------------- | ---------------------------- |
| `list`           | Show installed hooks         |
| `install <name>` | Install a hook from template |
| `remove <name>`  | Remove a hook                |
| `run <name>`     | Test a hook manually         |

### Available Hooks

| Hook          | Triggered                |
| ------------- | ------------------------ |
| `pre-commit`  | Before commit is created |
| `post-commit` | After commit is created  |
| `pre-merge`   | Before merge starts      |
| `post-merge`  | After merge completes    |

### Examples

```bash theme={null}
# List installed hooks
wit hooks

# Install pre-commit hook
wit hooks install pre-commit

# Test the hook
wit hooks run pre-commit

# Remove a hook
wit hooks remove pre-commit
```

### Hook Location

Hooks are stored in `.wit/hooks/`. Edit them to customize behavior:

```bash theme={null}
# Example pre-commit hook
#!/bin/bash
npm run lint
npm run test
```

<Info>
  For more details, see [Hooks](/features/hooks).
</Info>

***

## Submodules

Manage nested repositories within your project.

```bash theme={null}
wit submodule <command> [options]
```

### Commands

| Command            | Description                           |
| ------------------ | ------------------------------------- |
| `add <url> <path>` | Add a submodule                       |
| `init`             | Initialize submodules                 |
| `update`           | Update submodules to recorded commits |
| `status`           | Show submodule status                 |
| `foreach <cmd>`    | Run command in each submodule         |

### Examples

```bash theme={null}
# Add a submodule
wit submodule add https://github.com/lib/utils.git vendor/utils

# Initialize after cloning
wit submodule init

# Update to latest recorded commits
wit submodule update

# Check status
wit submodule status

# Run a command in all submodules
wit submodule foreach "npm install"
```

<Info>
  For more details, see [Submodules](/features/submodules).
</Info>

***

## Worktrees

Work on multiple branches simultaneously with multiple working directories.

```bash theme={null}
wit worktree <command> [options]
```

### Commands

| Command               | Description                   |
| --------------------- | ----------------------------- |
| `add <path> <branch>` | Create new worktree           |
| `list`                | List all worktrees            |
| `remove <path>`       | Remove a worktree             |
| `prune`               | Remove stale worktree entries |

### Examples

```bash theme={null}
# Create worktree for feature development
wit worktree add ../feature-worktree feature-branch

# List all worktrees
wit worktree list

# Remove when done
wit worktree remove ../feature-worktree

# Clean up stale entries
wit worktree prune
```

### Use Case

```bash theme={null}
# You're working on a feature but need to hotfix main
wit worktree add ../hotfix main

# Now you have two directories:
# - /project (your feature work, untouched)
# - /hotfix (clean main branch)

cd ../hotfix
# Fix the bug...
wit commit -a -m "Hotfix: critical bug"

# Go back to feature work
cd ../project
# Your feature branch is exactly as you left it!

# Clean up
wit worktree remove ../hotfix
```

<Info>
  For more details, see [Worktrees](/features/worktrees).
</Info>

***

## Reflog

View reference history for recovery.

```bash theme={null}
wit reflog [ref] [options]
```

### Options

| Option   | Description              |
| -------- | ------------------------ |
| `expire` | Prune old reflog entries |

### Examples

```bash theme={null}
# Show HEAD reflog
wit reflog

# Show reflog for specific branch
wit reflog main

# Prune old entries
wit reflog expire
```

### Example Output

```
HEAD@{0}: commit: Add authentication
HEAD@{1}: switch: moving from feature to main
HEAD@{2}: commit: Fix login bug
HEAD@{3}: merge: feature-auth
HEAD@{4}: commit: Initial setup
```

<Note>
  The reflog is what powers `wit undo`. Every operation is recorded and can be reversed.
</Note>

***

## Garbage Collection

Clean up and optimize the repository.

```bash theme={null}
wit gc [options]
```

### Options

| Option           | Description                               |
| ---------------- | ----------------------------------------- |
| `--aggressive`   | More thorough optimization (slower)       |
| `--prune=<date>` | Prune objects older than date             |
| `--prune=now`    | Prune all unreachable objects immediately |

### Examples

```bash theme={null}
# Standard garbage collection
wit gc

# Aggressive optimization
wit gc --aggressive

# Prune immediately
wit gc --prune=now
```

### When to Run

* After deleting many branches
* After undoing many operations
* When repository feels slow
* Before backing up (reduces size)

***

## Monorepo Scopes

Limit operations to specific paths in a monorepo.

```bash theme={null}
wit scope <command> [path]
```

### Commands

| Command        | Description                   |
| -------------- | ----------------------------- |
| `set <path>`   | Set the current scope         |
| `use <preset>` | Use a predefined scope        |
| `clear`        | Clear scope (full repository) |
| (none)         | Show current scope            |

### Examples

```bash theme={null}
# Check current scope
wit scope

# Limit to src directory
wit scope set src/

# Use preset
wit scope use frontend

# Clear scope
wit scope clear
```

### Effect on Commands

When a scope is set:

```bash theme={null}
wit scope set packages/frontend/

wit status    # Shows only frontend files
wit add .     # Stages only frontend files
wit log       # Shows commits affecting frontend
wit diff      # Shows changes in frontend only
```

<Info>
  For more details, see [Monorepo Scopes](/features/monorepo-scopes).
</Info>

***

## Plumbing Commands

Low-level commands for scripting and advanced use.

### hash-object

```bash theme={null}
wit hash-object <file>
```

Calculate the hash of a file.

### cat-file

```bash theme={null}
wit cat-file <hash>
```

Display contents of an object.

### ls-tree

```bash theme={null}
wit ls-tree <tree-hash>
```

List contents of a tree object.

### ls-files

```bash theme={null}
wit ls-files
```

List files in the index.

### rev-parse

```bash theme={null}
wit rev-parse <rev>
```

Parse a revision to its hash.

### for-each-ref

```bash theme={null}
wit for-each-ref
```

Iterate over references.

### update-ref

```bash theme={null}
wit update-ref <ref> <hash>
```

Update a reference.

### symbolic-ref

```bash theme={null}
wit symbolic-ref <name>
```

Read or set a symbolic reference.

### show-ref

```bash theme={null}
wit show-ref
```

List references.