# Temporarily disable existing violations with baseline





Adding katachi to an existing project means that on the first run, **undeclared files and directories come out as violations.** The basic approach is to work through the reported paths one by one — adding them to the definition, moving them, or deleting them — but when there are a lot of them, you can't clear them all right away.

baseline is a feature that **temporarily suppresses existing violations, so that new violations fail the test**.

## Setting it up

### 1. Write `baseline()` in the definition

```kt title="ProjectArchitecture.kt (excerpt)" {3}
val projectArchitecture: Architecture = architecture {
    // ...
    baseline()

    // ...
}
```

When you set baseline, by default the project root's `katachi-baseline.json` is used as the baseline file.

### 2. Declare the baseline file itself with `layout { }`

The baseline file is also one of the project's files, so unless it's declared as a role, `projectArchitecture.assert()` will error out.

Following convention, prepare a role named `"BaselineFile"` and add it to your architecture definition.

```kt
val projectArchitecture = architecture {
    // ...
    "Tool".group {
      "Katachi".group {
        baselineFile()
      }
    }

    // ...
}

fun DeclarationContainerScope.baselineFile() = "BaselineFile" {
    title = "katachi Baseline file"
    summary = "A file for temporarily suppressing existing violations"
    description = "See: https://tbsten.github.io/katachi/guides/baseline/"
    layout {
        "katachi-baseline.json".file()
    }
}
```

### 3. Create the baseline file

Running the architecture test with `-Dkatachi.baseline.update=true` makes all violations pass instead of erroring, and writes them into the baseline file.

```shell
./gradlew :architecture-test:test -Dkatachi.baseline.update=true
```

It's recommended to commit the created/updated file.

## After you fix a tolerated violation

When you fix a violation that had been tolerated, the baseline file is left with a record of a violation that no longer exists. If left alone, a different file placed at the same path later would pass silently, so katachi reports these leftovers as `[StaleBaselineEntry]` and **fails the test.**

To remove fixed violations from the baseline file, run the architecture test again with `-Dkatachi.baseline.prune=true`.

```shell
./gradlew :architecture-test:test -Dkatachi.baseline.prune=true
```

prune only **reduces** the number of records. It never adds new violations to the baseline file (that is the job of `-Dkatachi.baseline.update=true`). Commit the baseline file again once its violations have gone down.

## Summary

- baseline is a feature that records existing violations in the baseline file and temporarily suppresses them, so that only **newly added violations, and entries still in the baseline file after they were fixed,** fail the test.
- The baseline file is created and updated by running the architecture test with `-Dkatachi.baseline.update=true`. Commit the resulting file.
- When you fix a tolerated violation, the entries left in the baseline file fail the test as `[StaleBaselineEntry]`. `-Dkatachi.baseline.prune=true` removes the violations you have fixed.

## Next steps

- [Your first architecture definition](/katachi/get-started/first-architecture/) ... How to write your first definition, before tolerating any existing violations with a baseline.