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

# Branches

> Create, switch, and manage branches

wit provides intuitive branch management with automatic stashing when switching branches.

## branch

List, create, or delete branches.

```bash theme={null}
wit branch [name] [options]
```

### Options

| Option           | Description                          |
| ---------------- | ------------------------------------ |
| `-d <name>`      | Delete a branch                      |
| `-D <name>`      | Force delete a branch                |
| `-m <old> <new>` | Rename a branch                      |
| `-a`             | List all branches (including remote) |

### Examples

```bash theme={null}
# List all branches
wit branch

# Create a new branch
wit branch feature-login

# Delete a branch
wit branch -d feature-login

# Force delete (unmerged branch)
wit branch -D experimental

# Rename a branch
wit branch -m old-name new-name
```

### Example Output

```
  develop
  feature-auth
* main
  staging
```

The `*` indicates the current branch.

***

## switch

Switch to a different branch.

```bash theme={null}
wit switch <branch> [options]
```

### Options

| Option      | Description                          |
| ----------- | ------------------------------------ |
| `-c <name>` | Create a new branch and switch to it |
| `-`         | Switch to the previous branch        |

### Examples

```bash theme={null}
# Switch to existing branch
wit switch develop

# Create and switch
wit switch -c feature-new

# Go back to previous branch
wit switch -
```

<Note>
  When you switch branches, wit automatically saves your uncommitted changes and restores them when you switch back. No more losing work!
</Note>

***

## checkout

Git-compatible alias for switching branches and restoring files.

```bash theme={null}
wit checkout <branch>
wit checkout -b <new-branch>
```

### Options

| Option      | Description                          |
| ----------- | ------------------------------------ |
| `-b <name>` | Create a new branch and switch to it |

### Examples

```bash theme={null}
# Switch to a branch
wit checkout main

# Create and switch
wit checkout -b feature-new
```

<Tip>
  We recommend using `wit switch` for branches and `wit restore` for files, as they make intent clearer. `checkout` is provided for Git compatibility.
</Tip>

***

## Auto-Stash Feature

One of wit's best features is automatic stashing when switching branches.

### How It Works

1. When you switch branches with uncommitted changes:
   * wit saves your changes to a branch-specific stash
   * You switch to the new branch with a clean state

2. When you switch back:
   * wit automatically restores your saved changes
   * You can continue exactly where you left off

### Example

```bash theme={null}
# You're on main with uncommitted changes
wit status
# Shows: modified src/feature.ts

# Switch to fix a bug (changes are auto-saved)
wit switch hotfix-branch

# Work on the hotfix...
wit commit -a -m "Fix critical bug"

# Switch back (changes are auto-restored)
wit switch main

wit status
# Shows: modified src/feature.ts (your changes are back!)
```

### Configuration

Auto-stash is enabled by default. You can control it in `.wit/config`:

```ini theme={null}
[wit]
    autoStashOnSwitch = true
```

***

## Branch Workflow Example

```bash theme={null}
# 1. Start from main
wit switch main

# 2. Create a feature branch
wit switch -c feature-user-auth

# 3. Work on your feature...
wit add .
wit commit -m "Add login form"

# 4. Need to fix something on main?
wit switch main  # Auto-saves any uncommitted work

# 5. Fix and commit on main
wit commit -a -m "Fix typo"

# 6. Go back to feature
wit switch feature-user-auth  # Auto-restores your work

# 7. Continue working on feature...
```