# tmuxxer configuration

tmuxxer stores its config at:

```text
$XDG_CONFIG_HOME/tmuxxer/config
```

If `XDG_CONFIG_HOME` is not set, it uses:

```text
~/.config/tmuxxer/config
```

Check the exact path with:

```bash
tmuxxer config path
```

Start with `tmuxxer init`. It asks which folders to scan, writes the config, and keeps existing ignore rules. Use `tmuxxer user-config` later if you want to reconfigure the Ctrl+F shell/tmux bindings or Docker picker behavior.

## Example

New configs use TOML:

```toml
# Generated by tmuxxer setup

version = 2

[sources]
sessions = true
directories = true
docker = true

[session]
name_strategy = "path"

[docker]
new_session = true

[updates]
auto_check = true

[search]
ignore = ["target", ".git", "node_modules"]

[[search.roots]]
path = "~/code"
depth = 1

[[search.roots]]
path = "~/work"
depth = 3
```

`version` is optional, but if you set it, it must be `2`. Unknown keys are rejected so typos fail loudly. At least one picker source must stay enabled, and directory entries need at least one `[[search.roots]]`.

## Common changes

```bash
tmuxxer config set sources.docker false          # hide Docker containers
tmuxxer config set docker.new_session false      # open Docker shells in the current pane
tmuxxer config set updates.auto_check false      # disable background update checks
tmuxxer config set session.name_strategy basename
tmuxxer config toggle sources.docker
```

You can also disable update checks with:

```bash
tmuxxer update --disable-auto
```

Or skip them for one command:

```bash
TMUXXER_NO_UPDATE_CHECK=1 tmuxxer
```

Add or remove a search root:

```bash
tmuxxer --add ~/code
```

`--add` is a toggle. New roots use `depth = 1`. tmuxxer will not remove the last root while `sources.directories = true`, because that would make the config invalid.

Add or remove ignore patterns:

```bash
tmuxxer --ignore target
tmuxxer --ignore node_modules
tmuxxer --ignore ~/work/tmp
```

`--ignore` is also a toggle when you pass values. Run `tmuxxer --ignore` with no values for the interactive prompt.

## Settings

| Setting | Default | What it does |
| --- | --- | --- |
| `sources.sessions` | `true` | Shows existing tmux sessions. |
| `sources.directories` | `true` | Shows directories found under `search.roots`. |
| `sources.docker` | `true` | Shows running Docker containers when Docker is available. |
| `session.name_strategy` | `"path"` | Uses `"path"` or `"basename"` for directory session names. |
| `docker.new_session` | `true` | Opens Docker entries in a new tmux session. Set `false` to use the current pane. |
| `updates.auto_check` | `true` | Checks for new tmuxxer releases in the background. |
| `search.ignore` | `[]` | Folders or paths to skip while scanning. |
| `search.roots[].path` | required | Folder to scan for projects. `~` and `~/...` use `$HOME`. |
| `search.roots[].depth` | `1` | How many levels below the root to scan. `0` becomes `1`. |

Booleans in the TOML file must be `true` or `false`. With `tmuxxer config set`, these also work: `yes`, `y`, `1`, `on`, `no`, `n`, `0`, `off`.

## Search roots

A search root is a folder tmuxxer scans for projects:

```toml
[[search.roots]]
path = "~/code"
depth = 1
```

`depth = 1` lists direct children like `~/code/api` and `~/code/site`. `depth = 2` also finds one level deeper, like `~/code/tools/cli`. Larger depths are useful for nested workspaces, but they make tmuxxer scan more directories.

## Ignore patterns

```toml
[search]
ignore = [
  "target",
  ".git",
  "node_modules",
  "node_modules/*",
  "~/work/tmp",
]
```

Rules:

- `target` matches any folder named `target`.
- `.*` matches hidden path components like `.git`.
- `node_modules/*` matches relative paths below each search root.
- `~/work/tmp` and `/absolute/path` match absolute paths.
- `./folder/` is saved as `folder`.
- `*` is supported as a simple wildcard.

Command-line ignores are normalized before saving. For example, an existing `./tmp` is saved as a stable path.

## Session names

`session.name_strategy = "path"` is the default and recommended option. It creates readable names and adds a number only when needed, so two different `api` projects become `api` and `api-2`.

`session.name_strategy = "basename"` keeps the older behavior: only the folder name is used, and dots become underscores. Projects with the same folder name can collide more easily.

## Config commands

```bash
tmuxxer config list
tmuxxer config get sources.docker
tmuxxer config set sources.docker false
tmuxxer config toggle sources.docker
tmuxxer config validate
tmuxxer config migrate
```

`get`, `set`, and `toggle` support:

```text
sources.sessions
sources.directories
sources.docker
docker.new_session
updates.auto_check
session.name_strategy
```

Only boolean keys can be toggled. Manage `search.roots` and `search.ignore` with `tmuxxer init`, `tmuxxer --add`, `tmuxxer --ignore`, or by editing the file.

## Legacy config

Old key/value configs still load:

```ini
docker_new_session = true
path = ~/code
depth = 1
ignore = target
```

`path` adds a root. `depth` sets the previous root depth, or the default for following roots if it appears before any `path`. `ignore` adds one ignore pattern. `docker_new_session` maps to `docker.new_session`.

Any command that saves config rewrites legacy files as TOML v2.
