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

> ## Agent Instructions
> Bach builds Windows installers from one bach.toml with the bach command: bach init, bach check, bach preview, bach build. Installs are per user and need no administrator rights by default. installer.scope = "machine" installs for every user after one Windows prompt. On Windows, run setup files with Start-Process -Wait -PassThru in PowerShell, and give signtool arguments that start with the word sign.

# [files]: choose the folder and leave files out

> Reference for the [files] section of bach.toml: the source folder that gets installed and the exclude patterns that keep build leftovers out.

The `[files]` section names the folder Bach installs and the files in it to leave out. It is required.

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[files]
source = "target/release/package"
exclude = ["*.pdb", "docs/**"]
```

| Setting | Required | Meaning |
| - | - | - |
| `source` | yes | The folder whose contents are installed, subfolders included. Relative to `bach.toml`. |
| `exclude` | no | Patterns to leave out. |
| `allow_secrets` | no | Patterns, with the same rules as `exclude`, for files that look like secrets but are meant to ship. |

## Exclude patterns

* `*` matches within a name.
* `**` matches across folders.
* `?` matches one character.
* A pattern without `/` matches file names anywhere, like `*.pdb`.
* A pattern with `/` matches from the top of `source`, like `docs/**`.
* Case does not matter.

Typical Rust leftovers to exclude: `*.pdb`, `*.d`, `*.rlib`, `build/**`, `deps/**`, `incremental/**`, `.fingerprint/**`, `examples/**` and `bundle/**`. `bach init` writes these for Rust and Tauri projects, and `*.pdb`, `*.log`, `Thumbs.db` and `.DS_Store` for the other stacks it recognises.

## Secrets

`bach check` and `bach build` stop when `source` holds a file that looks like a secret, because a key that ships in a setup file is burnt. The message names the first file and why. These are refused:

* `.env`, `.env.*` and `*.env`
* `*.pfx`, `*.p12`, `*.pem`, `*.key`, `*.ppk`, `*.p8`, `*.snk`, `*.jks`, `*.keystore` and `*.kdbx`
* `id_rsa*`, `id_dsa*`, `id_ecdsa*` and `id_ed25519*`
* `secring.gpg` and `trustdb.gpg`
* `*.tfstate`, `*.tfvars`, `credentials`, `credentials.json`, `service-account*.json` and `local.settings.json`
* `.git-credentials`, `.npmrc`, `.yarnrc.yml`, `.pypirc`, `.netrc`, `.htpasswd`, `.dockercfg`, `.pgpass`, `.vault-token`, `.aws-credentials`, `.bash_history`, `.zsh_history`, `wallet.dat` and `secrets.json`
* a file called `.git`
* `bach.toml` and `bach-*.toml`, which hold your signing commands and feed addresses
* anything inside a `.git`, `.svn`, `.hg`, `.ssh`, `.aws`, `.azure`, `.gnupg`, `.docker`, `.kube` or `.terraform` folder
* `.m2/settings.xml`, `.gradle/gradle.properties`, `.gem/credentials` and anything inside `.config/gcloud`

Small text files in configuration formats (`.json`, `.yml`, `.yaml`, `.toml`, `.ini`, `.cfg`, `.conf`, `.config`, `.properties`, `.txt`, `.xml`, `.env`, `.pem` and scripts, up to 256 KiB) are also read for a private key block, an AWS access key (`AKIA...`), a GitHub token (`ghp_...`, `github_pat_...`) or a Slack token (`xoxb-...`). Programs and libraries are never read.

Leave the file out with `exclude`, or name it in `allow_secrets` to ship it on purpose:

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[files]
source = "build"
allow_secrets = ["config/public.pem"]
```

Files that only add weight give a warning instead: `*.pdb`, `*.log`, `Thumbs.db`, `.DS_Store` and anything inside `node_modules`, `target` or `__pycache__`.

## Rules

* Every file and folder name must be one Windows can create: at most 255 characters, counted as Windows counts them, and not a device name such as `NUL`, `CON`, `COM1` or `LPT1`, with or without an extension. `bach check` reports the first one that is not.
* The source folder cannot contain symbolic links. Copy real files into it. Bach reports the offending path.
* The source folder cannot contain a file named `uninstall.exe` at its top, because Bach adds its own.
* Every file you leave in is installed, unless a [component](/docs/reference/config/components.md) the user unticks claims it.
* Windows' classic limit for a whole path is 260 characters. Setup writes longer paths, but shortcuts, Explorer and many programs stop there unless Windows' long path support is on. `bach check` adds up the usual install folder (`%LOCALAPPDATA%\Programs\<folder>` with a 20-character user name, or `C:\Program Files\<folder>`) and the longest packaged path, and warns above 259 characters. Flatten deep trees such as `node_modules`.
* A file list of more than about 2 MB (roughly 17,000 files) also warns: the list is stored in the setup file and again in `uninstall.exe`. Fewer, larger files keep both smaller, for example an asar archive for an Electron app.

> [!TIP]
>
> Run `bach check` to see exactly which files will be installed after your excludes are applied.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.