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

# fallow init

> CLI reference for fallow init. Generate a .fallowrc.json, .fallowrc.jsonc, or fallow.toml configuration file with schema support for editor autocomplete.

Create a configuration file for your project. The generated config includes a `$schema` field so your editor can provide autocomplete and validation.

<Info>
  Most projects don't need a config file. Fallow works out of the box by auto-detecting entry points and frameworks. Only create one if you need custom entry points, rules, or ignore patterns.
</Info>

Fallow's init command auto-detects your project setup and tailors the generated config accordingly:

* **TypeScript**: Detects `tsconfig.json` and enables TypeScript-aware defaults
* **Monorepo**: Detects workspace configurations (npm, yarn, pnpm) and includes workspace patterns
* **Frameworks**: Detects installed frameworks (Next.js, Remix, Vite, etc.) and adds appropriate entry point patterns

```bash theme={null}
fallow init
```

## Options

| Flag             | Description                                                                                                     |
| :--------------- | :-------------------------------------------------------------------------------------------------------------- |
| `--toml`         | Generate `fallow.toml` instead of `.fallowrc.json`                                                              |
| `--hooks`        | Scaffold a pre-commit git hook that runs fallow on changed files. Alias for `fallow hooks install --target git` |
| `--branch <REF>` | Fallback base branch for the hook when no upstream is set (requires `--hooks`, default: `main`)                 |

## Pre-commit hook

Use the hooks namespace to scaffold a git hook that runs `fallow audit` against the base branch before each commit:

```bash theme={null}
fallow hooks install --target git
```

`fallow init --hooks` remains available as a project-initialization shortcut.

Fallow detects your hook manager and writes to the right location:

1. **Husky** -- adds to `.husky/pre-commit`
2. **Lefthook** -- adds to `lefthook.yml`
3. **Bare hooks** -- writes `.git/hooks/pre-commit`

The generated hook:

* Includes a binary guard (`command -v fallow`) so commits still work when fallow isn't installed
* Resolves the base ref at commit time: `git merge-base @{upstream} HEAD` when an upstream is set, falling back to the configured branch (or `main`) otherwise. Feature branches forked from a non-default integration branch (next-release / hotfix / LTS) compare against the right base, not against their own remote tracking branch
* Runs `fallow audit --base "$BASE" --quiet`, which combines dead-code, complexity, and duplication analysis
* Defaults to `gate=new-only`, so inherited findings on touched files do not block the commit; only findings introduced by the changeset fail the gate. Set `[audit] gate = "all"` in `fallow.toml` to fail on every finding in changed files
* Returns exit code 1 on `verdict: "fail"` (default audit semantics); no `--fail-on-issues` is needed
* Prints `git commit --no-verify` as the bypass option in the success message

<Info>
  Want to gate Claude Code or Codex agent commits as well? Use [`fallow hooks install --target agent`](/integrations/claude-hooks) for the agent enforcement path. The two hooks are complementary: `fallow hooks install --target git` catches human commits, `fallow hooks install --target agent` catches agent commits.
</Info>

### Custom base branch

By default, the hook compares against the merge-base of the current branch's upstream and `HEAD`, falling back to `main` when no upstream is set. Override the fallback with `--branch`:

```bash theme={null}
fallow hooks install --target git --branch develop
```

## Gitignore

`fallow init` automatically adds `.fallow/` to your project's `.gitignore`. The `.fallow/` directory contains machine-local data (parse cache, regression baselines, snapshots) that should not be committed.

* If `.gitignore` exists and already contains `.fallow/`, nothing changes
* If `.gitignore` exists without it, the entry is appended
* If `.gitignore` doesn't exist, it is created

## Output

<Tip>
  The generated config includes a `$schema` field for IDE autocomplete. Editors like VS Code will provide inline validation and suggestions automatically.
</Tip>

By default, creates `.fallowrc.json`:

```jsonc theme={null}
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "rules": {}
}
```

With `--toml`, creates `fallow.toml`.

## See also

<CardGroup cols={2}>
  <Card title="Configuration overview" icon="gear" href="/configuration/overview">
    Full reference for all configuration options.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Get started with fallow in under a minute.
  </Card>
</CardGroup>