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

# Configuration Overview

> Configure wit to match your workflow

wit stores configuration in `.wit/config` using an INI-like format, similar to Git.

## Configuration Levels

| Level      | Location         | Scope                 |
| ---------- | ---------------- | --------------------- |
| Repository | `.wit/config`    | This repository only  |
| Global     | `~/.witconfig`   | All your repositories |
| System     | `/etc/witconfig` | All users (rare)      |

Lower levels override higher levels: Repository > Global > System.

## Viewing Configuration

```bash theme={null}
# View all settings
wit config --list

# View specific setting
wit config core.hashAlgorithm

# View with source location
wit config --list --show-origin
```

## Setting Configuration

```bash theme={null}
# Set repository config
wit config <key> <value>

# Set global config
wit config --global <key> <value>
```

**Examples:**

```bash theme={null}
# Set user info (global)
wit config --global user.name "Your Name"
wit config --global user.email "you@example.com"

# Set repository-specific setting
wit config wit.autoStashOnSwitch false
```

## Configuration Sections

### Core Settings

```ini theme={null}
[core]
    repositoryformatversion = 1
    filemode = true
    bare = false
```

| Key                       | Description               | Default |
| ------------------------- | ------------------------- | ------- |
| `repositoryformatversion` | Repository format version | `1`     |
| `filemode`                | Track file permissions    | `true`  |
| `bare`                    | Is this a bare repository | `false` |

### wit Settings

```ini theme={null}
[wit]
    hashAlgorithm = sha1
    largeFileThreshold = 2097152
    autoStashOnSwitch = true
    chunkSize = 2097152
```

| Key                  | Description                                               | Default         |
| -------------------- | --------------------------------------------------------- | --------------- |
| `hashAlgorithm`      | Hash algorithm (sha1 for Git compat, sha256 for wit-only) | `sha1`          |
| `largeFileThreshold` | Size for large file handling                              | `2097152` (2MB) |
| `autoStashOnSwitch`  | Auto-save on branch switch                                | `true`          |
| `chunkSize`          | Chunk size for large files                                | `2097152` (2MB) |

### User Settings

```ini theme={null}
[user]
    name = Your Name
    email = you@example.com
```

### Remote Settings

```ini theme={null}
[remote "origin"]
    url = https://github.com/user/repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*
```

### Branch Settings

```ini theme={null}
[branch "main"]
    remote = origin
    merge = refs/heads/main
```

## Quick Reference

### Essential Settings

```bash theme={null}
# Your identity
wit config --global user.name "Your Name"
wit config --global user.email "you@example.com"

# Editor
wit config --global core.editor "code --wait"

# Default branch
wit config --global init.defaultBranch main
```

### wit-Specific Settings

```bash theme={null}
# Disable auto-stash
wit config wit.autoStashOnSwitch false

# Change large file threshold to 5MB
wit config wit.largeFileThreshold 5242880

# Use SHA-1 for Git compatibility (not recommended)
wit config wit.hashAlgorithm sha1
```

## Configuration File Format

```ini theme={null}
# Comments start with # or ;
[section]
    key = value
    anotherKey = another value

[section "subsection"]
    key = value

# Boolean values
[feature]
    enabled = true
    disabled = false

# Numbers
[limits]
    maxSize = 1048576
```

## Example Configuration

Complete `.wit/config`:

```ini theme={null}
[core]
    repositoryformatversion = 1
    filemode = true
    bare = false

[wit]
    hashAlgorithm = sha1
    largeFileThreshold = 2097152
    autoStashOnSwitch = true

[user]
    name = Alice Developer
    email = alice@example.com

[remote "origin"]
    url = git@github.com:alice/my-project.git
    fetch = +refs/heads/*:refs/remotes/origin/*

[branch "main"]
    remote = origin
    merge = refs/heads/main

[scope "frontend"]
    paths = packages/frontend/

[scope "backend"]
    paths = packages/backend/,packages/api/

```

## AI Configuration

AI features are configured via environment variables rather than config files:

```bash theme={null}
# OpenAI (default)
export OPENAI_API_KEY=sk-your-key-here

# OR Anthropic
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Optional: Change the model
export WIT_AI_MODEL=anthropic/claude-sonnet-4-20250514
```

| Variable            | Description       | Default         |
| ------------------- | ----------------- | --------------- |
| `OPENAI_API_KEY`    | OpenAI API key    | -               |
| `ANTHROPIC_API_KEY` | Anthropic API key | -               |
| `WIT_AI_MODEL`      | Model to use      | `openai/gpt-4o` |

Check AI status:

```bash theme={null}
wit ai status
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Repository Settings" icon="database" href="/configuration/repository">
    Deep dive into repository configuration
  </Card>

  <Card title="Directory Structure" icon="folder-tree" href="/configuration/directory-structure">
    Understanding .wit directory
  </Card>
</CardGroup>