### Initialize a new Tach project

Source: https://context7.com/tach-org/tach/llms.txt

Starts a guided setup for a new Tach project, including module boundary configuration and dependency syncing. Use --force to re-initialize if already configured.

```bash
# Initialize a new project
tach init

# Force re-initialization if already configured
tach init --force
```

--------------------------------

### tach init

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Initializes a new Tach project with a guided setup process.

```APIDOC
## tach init

Tach provides a guided setup process in `tach init`. This command will provide guidance and perform validation, while walking through `tach mod`, `tach sync` and `tach show`.

New users should start with this command.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Options
- **-h, --help** (flag) - Optional - show this help message and exit
- **--force** (flag) - Optional - Force re-initialization if project is already configured.
```

--------------------------------

### Closure Output Example

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Example output showing the transitive dependency list.

```json
[
  "src/core.py",
  "src/utils.py",
  "src/config.py",
  "src/constants.py"
]
```

--------------------------------

### Install dependencies

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/setting-up-project.md

Synchronizes project dependencies using uv.

```bash
./pw uv sync
```

--------------------------------

### Start local documentation server

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/working-with-docs.md

Launch a local development server with live reloading.

```bash
mkdocs serve
```

--------------------------------

### Sync documentation dependencies

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/working-with-docs.md

Install required dependencies for documentation development.

```bash
./pw uv sync --only-group docs
```

--------------------------------

### Initialize Tach

Source: https://github.com/tach-org/tach/blob/main/README.md

Run the interactive setup wizard to configure module boundaries and source roots.

```bash
 tach init
```

--------------------------------

### Install Tach via Pip

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

Use this command to install the Tach package using pip.

```bash
pip install tach
```

--------------------------------

### Example tach.toml Configuration

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

A comprehensive example demonstrating various configuration options in tach.toml, including exclude patterns, source roots, exact dependency checking, type checking imports, circular dependency checks, layer definitions, module configurations with dependencies and layers, interface definitions, cache settings, external exclusions, and rule severities.

```toml
exclude = [
    "**/*__pycache__",
    "build/",
    "dist/",
    "docs/",
    "python/tests/",
    "tach.egg-info/",
    "venv/",
]
source_roots = ["python"]
exact = true
ignore_type_checking_imports = true
forbid_circular_dependencies = true

layers = [
  "ui",
  "commands",
  "core"
]

[[modules]]
path = "tach"
depends_on = []

[[modules]]
path = "tach.__main__"
layer = "ui"

[[modules]]
path = "tach.errors"
depends_on = []
utility = true

[[modules]]
path = "tach.parsing"
depends_on = ["tach", "tach.filesystem"]
layer = "core"
visibility = ["tach.check"]

[[modules]]
path = "tach.check"
depends_on = [
    "tach.extension",
    "tach.filesystem",
    "tach.parsing",
]
layer = "commands"

[[interfaces]]
expose = ["types.*"]

[[interfaces]]
expose = [
    "parse_project_config",
    "dump_project_config_to_toml",
]
from = [
    "tach.parsing",
]

...

[cache]
file_dependencies = ["python/tests/**", "src/*.rs"]

[external]
exclude = ["pytest"]

[rules]
unused_ignore_directives = "warn"

```

--------------------------------

### Define File Tree Structure

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Example file tree representing a project with a root module.

```text
my_repo/
  tach.toml
  script.py
  lib/
    module1.py
    module2/
      __init__.py
      service.py
    module3.py
  docs/
  tests/
```

--------------------------------

### Configure CODEOWNERS for Domains

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Example mapping of domain configuration files to GitHub teams.

```CODEOWNERS
# Domain ownership for different teams

/tach.toml    @platform-team

/payments/tach.domain.toml    @payments-team
/auth/tach.domain.toml    @auth-team
/data/analytics/tach.domain.toml    @analytics-team @data-team
/mobile/tach.domain.toml    @mobile-team
/libs/shared/tach.domain.toml    @platform-team
```

--------------------------------

### Initialize Tach Project

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

Run this command to initialize a new Tach project. It will guide you through setting up module boundaries and create a tach.toml file.

```bash
tach init
```

--------------------------------

### Query Dependency Map with jq

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Examples of using jq to filter and analyze the dependency map output.

```bash
# Get dependencies for a specific file
tach map | jq '."src/core.py"'

# Find all files that depend on utils.py (using dependents direction)
tach map --direction dependents | jq '."src/utils.py"'

# Count dependencies for each file
tach map | jq 'map_values(length)'

# Find files with no dependencies
tach map | jq 'to_entries | map(select(.value | length == 0)) | map(.key)'
```

--------------------------------

### Import Statements in Backend Module

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Example imports rooted in the backend folder.

```python
# In backend/module1.py

import module3
from module2.service import MyService
```

--------------------------------

### Dependency Map JSON Output

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Example of the JSON structure returned by the map command.

```json
{
  "src/core.py": ["src/utils.py", "src/config.py"],
  "src/utils.py": [],
  "src/config.py": ["src/utils.py"]
}
```

--------------------------------

### Define Monorepo File Tree Structure

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Example file tree for a monorepo using namespace packages.

```text
my_repo/
  tach.toml
  utility/
    pyproject.toml
    src/
      myorg/
        utils/
          __init__.py
  core_one/
    pyproject.toml
    src/
      myorg/
        core_one/
          __init__.py
          module1.py
          module2/
            __init__.py
            service.py
          module3.py
  core_two/
    pyproject.toml
    src/
      myorg/
        core_two/
          __init__.py
          module1.py
          module2/
            __init__.py
            service.py
          module3.py
  docs/
  tests/
```

--------------------------------

### Python Import Example

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Example of an import statement within a Python module in a monorepo. The import path is resolved based on the configured source roots.

```python
from myorg.utils import utility_fn
```

--------------------------------

### Python Import Example (Alternative)

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

An alternative import statement, demonstrating how imports are resolved when the package name matches the directory structure.

```python
from utility import utility_fn
```

--------------------------------

### Define Module with Path and Dependencies

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Example of defining a module with its import path and specifying allowed dependencies. Glob patterns can be used for broader dependency matching.

```toml
[[modules]]
path = "a.b"
depends_on = ["c.d", "e.f.*"]

```

--------------------------------

### Example Interface Error Output

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

This example demonstrates an interface error reported by `tach check`. It highlights an import of a non-public member from a module with a defined public interface, specifying the file, the module, and the problematic import.

```bash
❌  tach/mod.py[L13]: Module 'tach.interactive' has a defined public interface. Only imports from the public interface of this module are allowed. The import 'tach.interactive.get_selected_modules_interactive' (in module 'tach.mod') is not public.
```

--------------------------------

### Example Dependency Error Output

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

This example shows a dependency error detected by `tach check`, indicating a forbidden import between modules. The output includes the file path, the module where the error occurred, and the module it attempted to import from.

```bash
> tach check
❌ tach/check.py[L8]: Cannot import 'tach.filesystem'. Module 'tach' cannot depend on 'tach.filesystem'.
```

--------------------------------

### Define Backend File Tree Structure

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Example file tree where Python code is contained within a backend subfolder.

```text
my_repo/
  tach.toml
  backend/
    module1.py
    module2/
      __init__.py
      service.py
    module3.py
  docs/
  tests/
```

--------------------------------

### Install pre-commit hook

Source: https://context7.com/tach-org/tach/llms.txt

Configure Tach as a pre-commit hook in your development workflow.

```bash
tach install pre-commit
```

--------------------------------

### Duration estimation output

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Example output showing the estimated time saved by skipping tests.

```text
[Tach] Skipped 42 tests (5 files) (~12.3s saved) - unaffected by current changes.
```

--------------------------------

### Get Transitive Dependencies

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Use the closure flag to find all direct and indirect dependencies.

```bash
# Get all direct and indirect dependencies of core.py
tach map --closure src/core.py
```

--------------------------------

### Define Module Dependencies and Interfaces in tach.toml

Source: https://github.com/tach-org/tach/blob/main/docs/usage/interfaces.md

Configure module dependencies and define public interfaces using `expose` and `from` patterns in `tach.toml`. This example shows 'domain' depending on 'core' and 'core' exposing 'get_data'.

```toml
[[modules]]
path = "domain"
depends_on = [
    "core"
]

[[modules]]
path = "core"
depends_on = []

[[interfaces]]
expose = ["get_data"]
from = ["core"]
```

--------------------------------

### Define Python code block

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/working-with-docs.md

Example of a standard Python code block in Markdown.

```python
def example_function():
    return "Hello, World!"
```

--------------------------------

### Install Tach Pre-commit Hook

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

Add Tach to your pre-commit hooks to automatically check module boundaries on each commit.

```bash
tach install --pre-commit
```

--------------------------------

### Define Interfaces with Visibility Constraints

Source: https://github.com/tach-org/tach/blob/main/docs/usage/interfaces.md

Configure interfaces in `tach.toml` with specific visibility. This example shows 'api' exposing 'read_data' to all consumers and 'write_data' only to 'admin.controller'.

```toml
[[modules]]
path = "api"
depends_on = []

[[interfaces]]
expose = ["read_data"]
from = ["api"]

[[interfaces]]
expose = ["write_data"]
from = ["api"]
visibility = ["admin.controller"]  # limiting visibility of this interface
```

--------------------------------

### Generate JSON dependency map

Source: https://context7.com/tach-org/tach/llms.txt

Creates a JSON map detailing file-level dependencies. Output can be directed to stdout or a file. Options include showing dependents instead of dependencies, and getting the transitive closure for a specific file.

```bash
# Output to stdout
tach map

# Output to file
tach map -o deps.json

# Show dependents instead of dependencies
tach map --direction dependents

# Get transitive closure for a specific file
tach map --closure src/core.py
```

--------------------------------

### Violation Error Output

Source: https://github.com/tach-org/tach/blob/main/README.md

Example of an error message generated when an import violates dependency rules.

```text
❌ tach/check.py[L8]: Cannot use 'tach.filesystem'. Module 'tach' cannot depend on 'tach.filesystem'.
```

--------------------------------

### Python Import of Deprecated Dependency

Source: https://github.com/tach-org/tach/blob/main/docs/usage/deprecate.md

Example of a Python file importing a function from a module marked as deprecated. This import will be flagged by `tach check` but will not cause a check failure.

```python
from core.main import get_data # we want to remove this!

get_data()
```

--------------------------------

### Define Exclusive Interface with Visibility

Source: https://github.com/tach-org/tach/blob/main/docs/usage/interfaces.md

Configure an exclusive interface in `tach.toml`. This example makes the 'write_data' interface the sole way for 'admin.controller' to interact with the 'api' module.

```toml
[[modules]]
path = "api"
depends_on = []

[[interfaces]]
expose = ["read_data"]
from = ["api"]

[[interfaces]]
expose = ["write_data"]
from = ["api"]
visibility = ["admin.controller"]
exclusive = true  # marking this interface as 'exclusive'
```

--------------------------------

### Visualize Dependencies

Source: https://github.com/tach-org/tach/blob/main/README.md

Generate a dependency graph, optionally using the web interface or local GraphViz DOT format.

```bash
tach show [--web]
```

--------------------------------

### Report Dependencies

Source: https://github.com/tach-org/tach/blob/main/README.md

View dependencies and usages for a specific package path.

```bash
tach report my_package/
```

--------------------------------

### Check and sync dependencies

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/setting-up-project.md

Verifies and synchronizes dependencies in the root folder.

```bash
tach check
tach sync
```

--------------------------------

### Visualize project dependency graph

Source: https://context7.com/tach-org/tach/llms.txt

Generates a visualization of the project's dependency graph. Options include generating a local DOT file, opening an interactive web visualization, or creating a Mermaid.js graph. Specific paths can be included.

```bash
# Generate DOT file locally (tach_module_graph.dot)
tach show

# Open interactive web visualization
tach show --web

# Generate Mermaid.js graph
tach show --mermaid

# Specify output file path
tach show -o my_graph.dot

# Include only specific paths
tach show src/core src/api
```

--------------------------------

### Configure navigation in mkdocs.yml

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/working-with-docs.md

Add new pages to the documentation navigation structure.

```yaml
nav:
  - Home: index.md
  - Getting Started:
    - Overview: getting-started/introduction.md
    - # Add your new page here
    - My New Page: getting-started/my-new-page.md
```

--------------------------------

### Sync Project Dependencies

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Automatically sync your `tach.toml` configuration with your project's actual dependencies using `tach sync`. It analyzes imports and resolves undeclared dependencies. Use `--add` to include all existing constraints without removing unused ones.

```bash
usage: tach sync [-h] [--add] [-e file_or_path,...]

Sync constraints with actual dependencies in your project.

options:
  -h, --help            show this help message and exit
  --add                 add all existing constraints and re-sync dependencies.
  -e file_or_path,..., --exclude file_or_path,...
                        Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### Impact analysis warning output

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Example warning displayed when tests that would be skipped by impact analysis fail.

```text
[Tach] WARNING: 2 test(s) failed that would be skipped by impact analysis!
[Tach] These failures would be missed when using --tach:
[Tach]   - test_module.py::test_that_unexpectedly_failed
```

--------------------------------

### Define Module Dependencies

Source: https://context7.com/tach-org/tach/llms.txt

Define module paths and their dependencies within a domain. Use '//external.gateway' for external dependencies.

```toml
[[modules]]
path = "models"          # Defines "payments.models"
depends_on = []

[[modules]]
path = "validators"      # Defines "payments.validators"
depends_on = ["models"]

[[modules]]
path = "services"        # Defines "payments.services"
depends_on = ["models", "validators", "//external.gateway"]
```

--------------------------------

### Generate Dependency Map

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Displays the CLI usage for generating a dependency map.

```text
usage: tach map [-h] [-o OUTPUT] [--direction {dependencies,dependents}] [--closure CLOSURE]

Build a dependency map and write it to a file or stdout

options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Output file path. Use '-' for stdout (default: '-')
  --direction {dependencies,dependents}
                        Direction of the map (default: 'dependencies')
  --closure CLOSURE     Get the closure for a specific file path
```

--------------------------------

### Configure Three-Tier Architecture Layers

Source: https://context7.com/tach-org/tach/llms.txt

Define architectural layers and assign modules to them. Modules can freely import from layers below them but not from layers above.

```toml
# tach.toml - Three-tier architecture
layers = [
    "presentation",
    "business",
    "data"
]

[[modules]]
path = "api.controllers"
layer = "presentation"
# Can freely import from business and data layers

[[modules]]
path = "api.views"
layer = "presentation"

[[modules]]
path = "services.user"
layer = "business"
depends_on = ["services.auth"]  # Must declare same-layer dependencies

[[modules]]
path = "services.auth"
layer = "business"

[[modules]]
path = "repositories.user"
layer = "data"
depends_on = []
# Cannot import from presentation or business layers

[[modules]]
path = "repositories.cache"
layer = "data"
depends_on = ["repositories.user"]  # Must declare same-layer dependencies
```

--------------------------------

### Visualize Module Dependencies

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

Generates a graphical representation of your module dependencies.

```bash
tach show
```

--------------------------------

### Sync Dependencies with Codebase

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

This command analyzes your codebase and automatically adds dependency rules to your tach.toml file based on actual imports.

```bash
tach sync
```

--------------------------------

### Configure Source Roots

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Configuration snippet for setting the source root in tach.toml.

```toml
source_roots = ["backend"]
```

--------------------------------

### Map dependencies with jq

Source: https://context7.com/tach-org/tach/llms.txt

Use jq to query the dependency map generated by tach map.

```bash
tach map | jq '."src/core.py"'
```

```bash
tach map | jq 'to_entries | map(select(.value | length == 0)) | map(.key)'
```

```bash
tach map | jq 'map_values(length)'
```

--------------------------------

### Define Layer Configuration

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Sets up an ordered list of layers for the project, defining architectural tiers from highest to lowest.

```toml
layers = [
  "ui",
  "commands",
  "core"
]

```

--------------------------------

### Configure tach.domain.toml

Source: https://context7.com/tach-org/tach/llms.txt

Manage domain-specific module ownership and dependencies in subdirectories.

```toml
[root]
depends_on = [
    "//shared.utils",    # "//" prefix for absolute paths outside domain
    "models",            # Relative path: "payments.models"
    "validators",        # Relative path: "payments.validators"
]
```

--------------------------------

### Generate dependency and usage reports

Source: https://context7.com/tach-org/tach/llms.txt

Creates reports on module dependencies and usages within a specified directory or file. Supports filtering by dependencies, usages, external dependencies, and specific modules. Machine-readable output is available.

```bash
# Full report for a directory
tach report my_package/

# Full report for a specific file
tach report my_module.py

# Report only dependencies
tach report --dependencies my_package/

# Report only usages
tach report --usages my_package/

# Report only external (3rd party) dependencies
tach report --external my_package/

# Filter by specific dependency modules
tach report -d module1,module2 my_package/

# Filter by specific usage modules
tach report -u module1,module2 my_package/

# Machine-readable output
tach report --raw my_package/
```

--------------------------------

### Configure module boundaries interactively

Source: https://context7.com/tach-org/tach/llms.txt

Opens an interactive terminal-based editor to define module boundaries. Supports expanding directories to a specific depth and excluding paths. Interactive controls are provided for navigation and configuration.

```bash
# Open interactive module editor
tach mod

# Expand directories to a specific depth
tach mod -d 3

# Exclude specific paths from the editor
tach mod -e tests/,ci/,docs/
```

--------------------------------

### tach sync

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Automatically syncs your project configuration (`tach.toml`) with your project's actual dependencies.

```APIDOC
## tach sync

Tach can automatically sync your project configuration (`tach.toml`) with your project's actual dependencies.

When this command runs, Tach will analyze the imports in your Python project.

Any undeclared dependencies will be automatically resolved by adding the corresponding dependencies to your `tach.toml` file.

With `--add`, any missing dependencies in your `tach.toml` will be added, but does not remove unused dependencies.

When run without the `--add` flag, `tach sync` will remove modules from the `tach.yml` file that do not exist in the project's source roots.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Options
- **-h, --help** (flag) - Optional - show this help message and exit
- **--add** (flag) - Optional - add all existing constraints and re-sync dependencies.
- **-e file_or_path,..., --exclude file_or_path,...** (list of strings) - Optional - Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### Tach Show Command Usage

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Details the command-line usage for the 'tach show' command, used for visualizing the project's dependency graph. Options include generating a web viewer or a mermaid.js graph, and specifying an output file.

```bash
usage: tach show [-h] [--web] [--mermaid] [-o [OUT]] [included_paths ...]

Visualize the dependency graph of your project.

positional arguments:
  included_paths        Paths to include in the module graph. If not provided, the entire project is
                        included.

options:
  -h, --help            show this help message and exit
  --web                 Open your dependency graph in a remote web viewer.
  --mermaid             Generate a mermaid.js graph instead of a DOT file.
  -o [OUT], --out [OUT]
                        Specify an output path for a locally generated module graph file.
```

--------------------------------

### Run linting

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/setting-up-project.md

Executes linting checks for both Rust and Python code.

```bash
make lint
```

--------------------------------

### Synchronize project dependencies

Source: https://context7.com/tach-org/tach/llms.txt

Automatically syncs project configuration with actual code dependencies, adding missing ones and optionally removing unused ones. Paths can be excluded from analysis.

```bash
# Sync dependencies (removes unused, adds missing)
tach sync

# Only add missing dependencies without removing unused ones
tach sync --add

# Exclude specific paths from analysis
tach sync -e tests/,ci/
```

--------------------------------

### Define Module with Paths Shorthand

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Using the `paths` attribute as a shorthand to define multiple module dependencies at once.

```toml
[[modules]]
path = "a.b"
paths = ["c.d", "c.e"]

```

--------------------------------

### Configure tach.toml

Source: https://context7.com/tach-org/tach/llms.txt

Define project modules, layers, interfaces, and behavior settings in the main configuration file.

```toml
exclude = [
    "**/*__pycache__",
    "build/",
    "dist/",
    "docs/",
    "python/tests/",
    "venv/",
]

source_roots = ["python", "src"]

exact = true                          # Fail on unused dependencies
ignore_type_checking_imports = true   # Ignore TYPE_CHECKING imports
forbid_circular_dependencies = true   # Fail on circular dependencies
layers_explicit_depends_on = false    # Require explicit layer dependencies
respect_gitignore = true              # Respect .gitignore patterns

root_module = "ignore"

layers = [
    "ui",
    { name = "commands", closed = true },  # Closed layer prevents skipping
    "core"
]

[[modules]]
path = "myapp"
depends_on = []

[[modules]]
path = "myapp.api"
layer = "ui"
depends_on = ["myapp.services"]

[[modules]]
path = "myapp.services"
layer = "commands"
depends_on = ["myapp.repository"]
visibility = ["myapp.api"]  # Only api can import this module

[[modules]]
path = "myapp.repository"
layer = "core"
depends_on = []

[[modules]]
path = "myapp.utils"
utility = true              # All modules can import without declaring
depends_on = []

[[modules]]
path = "myapp.legacy"
unchecked = true            # Skip dependency checking for this module
depends_on = []

[[modules]]
path = "myapp.core"
depends_on = [
    { path = "myapp.oldlib", deprecated = true }  # Warn but don't fail
]

[[modules]]
path = "libs.**"            # Default config for all modules under libs
depends_on = []

[[interfaces]]
expose = ["get_data", "DataModel"]
from = ["myapp.repository"]

[[interfaces]]
expose = ["services.*"]     # Regex pattern
from = ["myapp.services"]

[[interfaces]]
expose = ["admin_*"]
from = ["myapp.api"]
visibility = ["myapp.admin"]  # Only admin can use this interface
exclusive = true              # Admin must use ONLY this interface

[cache]
file_dependencies = ["python/tests/**", "src/*.rs", "*.json"]
env_dependencies = ["DEBUG", "DATABASE_URL"]

[external]
exclude = ["pytest", "mypy"]  # Ignore these imports
rename = ["PIL:pillow"]       # Map module name to package name

[rules]
unused_ignore_directives = "warn"
require_ignore_directive_reasons = "off"
unused_external_dependencies = "error"
```

--------------------------------

### Run tests

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/setting-up-project.md

Executes the test suite using pytest.

```bash
make test
```

--------------------------------

### Generate Tach Reports

Source: https://github.com/tach-org/tach/blob/main/README.md

Use the report command to analyze dependencies and usages for a specific module or file path.

```bash
tach report my_module.py
```

```bash
> tach report python/tach/filesystem
[Dependencies of 'python/tach/filesystem']
python/tach/filesystem/install.py[L6]: Import 'tach.hooks.build_pre_commit_hook_content'
python/tach/filesystem/project.py[L5]: Import 'tach.constants.CONFIG_FILE_NAME'
...
-------------------------------
[Usages of 'python/tach/filesystem']
python/tach/cache/access.py[L8]: Import 'tach.filesystem.find_project_config_root'
python/tach/cache/setup.py[L7]: Import 'tach.filesystem.find_project_config_root'
...
```

--------------------------------

### Pytest Plugin Usage

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Commands for running pytest with Tach integration.

```bash
pytest
```

```bash
pytest --tach
```

```bash
pytest -p no:tach
```

--------------------------------

### Configure pre-commit hook

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Configuration for adding Tach to the .pre-commit-hooks.yaml file.

```yaml
repos:
  - repo: https://github.com/gauge-sh/tach-pre-commit
    rev: v0.30.0 # change this to the latest tag!
    hooks:
      - id: tach
```

--------------------------------

### Tach Report Command Usage

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Displays the command-line usage for the 'tach report' command, outlining options for generating dependency, usage, and external reports. Use flags like --dependencies, --usages, --external, and --raw for specific report types.

```bash
usage: tach report [-h] [--dependencies] [--usages] [--external] [-d module_path,...] [-u module_path,...] [--raw] [-e file_or_path,...] path

Create a report of dependencies and usages.

positional arguments:
  path                  The path or directory path used to generate the report.

options:
  -h, --help            show this help message and exit
  --dependencies        Generate dependency report. When present, all reports must be explicitly enabled.
  --usages              Generate usage report. When present, all reports must be explicitly enabled.
  --external            Generate external dependency report. When present, all reports must be explicitly enabled.
  -d module_path,..., --dependency-modules module_path,...
                        Comma separated module list of dependencies to include [includes everything by default]
  -u module_path,..., --usage-modules module_path,...
                        Comma separated module list of usages to include [includes everything by default]
  --raw                 Group lines by module and print each without any formatting.
  -e file_or_path,..., --exclude file_or_path,...
                        Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### Configure Module Boundaries Interactively

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

The `tach mod` command opens an interactive editor to define module boundaries. Navigate with arrow keys, mark modules with Enter, and siblings with Ctrl+a. Use 's' to mark source roots and 'u' for utility modules. Save with Ctrl+s or exit with Ctrl+c.

```bash
usage: tach mod [-h] [-d [DEPTH]] [-e file_or_path,...]

Configure module boundaries interactively

options:
  -h, --help            show this help message and exit
  -d [DEPTH], --depth [DEPTH]
                        The number of child directories to expand from the root
  -e file_or_path,..., --exclude file_or_path,...
                        Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### Format code

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/setting-up-project.md

Applies formatting rules to Rust and Python code.

```bash
make fmt
```

--------------------------------

### tach mod

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Configures module boundaries interactively.

```APIDOC
## tach mod

Tach provides an interactive editor for configuring your module boundaries - `tach mod`.

Running `tach mod` will open an editor in your terminal where you can mark your module boundaries.

You can navigate with the arrow keys, mark individual modules with `Enter`, and mark all siblings as modules with `Ctrl + a`.

You can also mark your Python [source roots](configuration.md#source-roots) by pressing `s`. This allows Tach to understand module paths and correctly identify first-party imports.

You can mark modules as [utilities](configuration.md#modules) by pressing `u`. This is appropriate for modules like `utils/`, which can be freely used by the rest of the code.

To save your modules, use `Ctrl + s`. Otherwise, to exit without saving, use `Ctrl + c`.

Any time you make changes with `tach mod`, run [`tach sync`](commands.md#tach-sync) to automatically configure dependency rules.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Options
- **-h, --help** (flag) - Optional - show this help message and exit
- **-d [DEPTH], --depth [DEPTH]** (integer) - Optional - The number of child directories to expand from the root
- **-e file_or_path,..., --exclude file_or_path,...** (list of strings) - Optional - Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### Run type checking

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/setting-up-project.md

Executes static type analysis.

```bash
make type-check
```

--------------------------------

### Define Interface Exposure and Adoption

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Configures public interfaces, specifying which parts of a module are exposed and which modules can adopt this interface.

```toml
[[interfaces]]
expose = ["services.*"]
from = ["my_module"]

```

--------------------------------

### Define Modules in tach.toml

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Standard module definition format for tach.toml files.

```toml
[[modules]]
path = "tach.filesystem"
depends_on = [
  "tach.hooks",
  "tach.filesystem.service",
]

[[modules]]
path = "tach.filesystem.service"
depends_on = []
```

--------------------------------

### Define Module Boundaries Interactively

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

Use the 'tach mod' command to open an interactive terminal UI for defining and managing your module boundaries.

```bash
tach mod
```

--------------------------------

### Define Module Interfaces

Source: https://context7.com/tach-org/tach/llms.txt

Define the public interface for modules, specifying which functions and types are exposed. Use '<domain_root>' to apply to the main domain module.

```toml
# Interface definitions for this domain
[[interfaces]]
expose = ["process_payment", "PaymentResult"]
from = ["<domain_root>"]  # Applies to "payments" module

[[interfaces]]
expose = ["validate_*"]
from = ["validators"]     # Applies to "payments.validators"
```

--------------------------------

### Check Module Boundary Violations

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

Execute this command to report any violations of your defined module boundaries or interfaces.

```bash
tach check
```

--------------------------------

### Define Interfaces in tach.toml

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Standard interface definition format for tach.toml files.

```toml
[[interfaces]]
expose = ["service.*"]
from = ["tach.filesystem"]

[[interfaces]]
expose = ["client.*"]
from = ["tach.filesystem.git_ops"]
```

--------------------------------

### TOML Configuration for Deprecated Dependency

Source: https://github.com/tach-org/tach/blob/main/docs/usage/deprecate.md

Define modules and their dependencies in TOML format. Mark a dependency as deprecated using `deprecated = true` within the `depends_on` list.

```toml
[[modules]]
path = "parsing"
depends_on = [
    { path = "core", deprecated = true }
]

[[modules]]
path = "core"
depends_on = []
```

--------------------------------

### Configure Tach Pre-commit Hook Manually

Source: https://github.com/tach-org/tach/blob/main/docs/getting-started/getting-started.md

Manually add Tach to your .pre-commit-config.yaml file for pre-commit hook integration.

```yaml
-   repo: local
    hooks:
    -   id: tach
        name: tach
        entry: tach check
        language: system
        pass_filenames: false
```

--------------------------------

### Tach Test CLI Usage

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Displays the CLI usage for the intelligent test runner.

```text
usage: tach test [-h] [--base [BASE]] [--head [HEAD]] [--disable-cache] ...
Run tests on modules impacted by the current changes.
positional arguments:
  pytest_args      Arguments forwarded to pytest. Use '--' to separate
                   these arguments. Ex: 'tach test -- -v'
options:
  -h, --help       show this help message and exit
  --base [BASE]    The base commit to use when determining which modules
                   are impacted by changes. [default: 'main']
  --head [HEAD]    The head commit to use when determining which modules
                   are impacted by changes. [default: current filesystem]
  --disable-cache  Do not check cache for results, and
                   do not push results to cache.
```

--------------------------------

### Reference images in Markdown

Source: https://github.com/tach-org/tach/blob/main/docs/contributing/working-with-docs.md

Syntax for embedding images stored in the assets directory.

```markdown
![Alt text](../assets/image-name.png)
```

--------------------------------

### Rename External Packages

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Mapping module names to package specifiers for external dependency resolution.

```toml
[external]
rename = [
  # Format "[module name]:[package name]"
  "PIL:pillow",
  ...
]
```

--------------------------------

### Define Modules in tach.domain.toml

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Domain-specific module definition using root and relative path syntax.

```toml
[root]  # This defines "tach.filesystem"
depends_on = [
  "//tach.hooks",  # This refers to "tach.hooks" (outside of this domain)
  "service",  # This refers to "tach.filesystem.service"
]

[[modules]]
path = "service"  # This defines "tach.filesystem.service"
depends_on = []
```

--------------------------------

### Define Source Roots in tach.toml

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Specify source root directories relative to the project root in `tach.toml` to help Tach understand the project structure. This is crucial for correctly resolving imports between packages in a monorepo.

```toml
source_roots = [
  "utility/src",
  "core_one/src",
  "core_two/src"
]
```

--------------------------------

### Define Public Interface for a Module

Source: https://context7.com/tach-org/tach/llms.txt

Specify the public API for a module using the 'expose' field in the 'interfaces' section. Consumers can only import exposed members.

```toml
# tach.toml
[[modules]]
path = "core"
depends_on = []

[[modules]]
path = "domain"
depends_on = ["core"]

# Public interface for core module
[[interfaces]]
expose = ["get_data", "DataModel", "exceptions.*"]
from = ["core"]
```

--------------------------------

### Enforce Public Interface in Imports

Source: https://context7.com/tach-org/tach/llms.txt

Demonstrates allowed and disallowed imports based on a module's public interface definition. Imports not matching the 'expose' list will fail.

```python
# domain/service.py

# This import is ALLOWED (matches interface)
from core import get_data, DataModel
from core.exceptions import ValidationError

# This import FAILS tach check (not in public interface)
from core.internal import _private_helper
# Error: Module 'core' has a defined public interface. The import 'core.internal._private_helper' is not public.
```

--------------------------------

### Check module boundaries and interfaces

Source: https://context7.com/tach-org/tach/llms.txt

Validates module boundaries and interfaces, suitable for pre-commit hooks and CI. Supports different checking modes like exact mode, dependency-only, and interface-only checks. Paths can be excluded.

```bash
# Check all module boundaries and interfaces
tach check

# Check with exact mode (fail on unused dependencies)
tach check --exact

# Check only dependency constraints
tach check --dependencies

# Check only interface implementations
tach check --interfaces

# Exclude specific paths
tach check -e tests/,ci/
```

--------------------------------

### Check Module Dependencies and Interfaces

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Use `tach check` to flag unwanted imports between modules. It can be integrated into pre-commit hooks or CI pipelines. Use `--dependencies` or `--interfaces` to limit checks to specific categories. The `--exact` flag ensures all declared dependencies are used.

```bash
usage: tach check [-h] [--exact] [--dependencies] [--interfaces] [-e file_or_path,...]

Check existing boundaries against your dependencies and module interfaces

options:
  -h, --help            show this help message and exit
  --exact               When checking dependencies, raise errors if any dependencies are unused.
  --dependencies        Check dependency constraints between modules. When present, all checks must be explicitly enabled.
  --interfaces          Check interface implementations. When present, all checks must be explicitly enabled.
  -e file_or_path,..., --exclude file_or_path,...
                        Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### Ignore with reasoning

Source: https://github.com/tach-org/tach/blob/main/docs/usage/tach-ignore.md

Provide a message in parentheses after the `tach-ignore` directive to document the reason for ignoring the import. The name of the import to ignore follows the reasoning.

```python
# tach-ignore(Alternative API not yet available 11/26/24) private_api
from core.api import private_api
```

--------------------------------

### Define Interfaces in tach.domain.toml

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Domain-specific interface definition using domain root relative paths.

```toml
[[interfaces]]
expose = ["service.*"]
from = ["<domain_root>"]  # This matches "tach.filesystem"

[[interfaces]]
expose = ["client.*"]
from = ["git_ops"]  # This matches "tach.filesystem.git_ops"
```

--------------------------------

### Failing Import Due to Private Implementation Detail

Source: https://github.com/tach-org/tach/blob/main/docs/usage/interfaces.md

This Python code demonstrates an import that would fail `tach check` because it attempts to access a private implementation detail ('core.main.DataModel') of the 'core' module, which has a public interface defined.

```python
from core.main import DataModel  # This import fails

DataModel.objects.all()
```

--------------------------------

### Tach Check External Command Line Usage

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

This command-line interface (CLI) usage describes the `tach check-external` command, including its help flag and an option to exclude specific files or paths from the check. Use this command to initiate the dependency validation process.

```bash
usage: tach check-external [-h] [-e file_or_path,...]

Perform checks related to third-party dependencies

options:
  -h, --help  show this help message and exit
  -e file_or_path,..., --exclude file_or_path,...
                        Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### tach check

Source: https://github.com/tach-org/tach/blob/main/docs/usage/commands.md

Flags unwanted imports between modules and checks dependency constraints and interface implementations.

```APIDOC
## tach check

Tach will flag any unwanted imports between modules. We recommend you run `tach check` like a linter or test runner, e.g. in pre-commit hooks, on-save hooks, and in CI pipelines.

Using the `--dependencies` or `--interfaces` flag will limit the checks performed to the respective category. By default, all checks will be performed.

### Dependency Errors
An error will indicate:
- the file path in which the error was detected
- the module associated with that file
- the module associated with the attempted import

If `--exact` is provided, additional errors will be raised if a dependency exists in `tach.toml` that does not exist in the code.

Example:
```bash
> tach check
❌ tach/check.py[L8]: Cannot import 'tach.filesystem'. Module 'tach' cannot depend on 'tach.filesystem'.
```

NOTE: If your terminal supports hyperlinks, you can click on the failing file path to go directly to the error.

### Interface Errors
An error will indicate:

- the file path in which the error was detected
- the module associated with that file
- the module associated with the attempted import
- the non-public member associated with the attempted import

Example:

```bash
❌  tach/mod.py[L13]: Module 'tach.interactive' has a defined public interface. Only imports from the public interface of this module are allowed. The import 'tach.interactive.get_selected_modules_interactive' (in module 'tach.mod') is not public.
```

NOTE: If your terminal supports hyperlinks, you can click on the failing file path to go directly to the error.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Options
- **-h, --help** (flag) - Optional - show this help message and exit
- **--exact** (flag) - Optional - When checking dependencies, raise errors if any dependencies are unused.
- **--dependencies** (flag) - Optional - Check dependency constraints between modules. When present, all checks must be explicitly enabled.
- **--interfaces** (flag) - Optional - Check interface implementations. When present, all checks must be explicitly enabled.
- **-e file_or_path,..., --exclude file_or_path,...** (list of strings) - Optional - Comma separated path list to exclude. tests/, ci/, etc.
```

--------------------------------

### Configure a Module Without Dependency Restrictions in TOML

Source: https://github.com/tach-org/tach/blob/main/docs/usage/faq.md

Define a module in `tach.toml` without the `depends_on` key to allow it to depend on any other module without restriction. This makes Tach aware of the module boundary for dependency tracking.

```toml
[[modules]]
path = "my.module"
# no 'depends_on' key here means this module can depend on anything
```

--------------------------------

### Define Module with Layer Assignment

Source: https://github.com/tach-org/tach/blob/main/docs/usage/configuration.md

Assigns a module to a specific layer within the project's architecture. Layers are defined globally.

```toml
[[modules]]
path = "tach.check"
layer = "commands"

```

--------------------------------

### Run impact-based tests

Source: https://context7.com/tach-org/tach/llms.txt

Execute tests using tach test or the pytest plugin to target affected modules.

```bash
tach test
```

```bash
tach test --base develop
```

```bash
tach test --head HEAD~1
```

```bash
tach test --disable-cache
```

```bash
tach test -- -v --tb=short
```

```bash
pytest
```

```bash
pytest --tach
```

```bash
pytest --tach-base main
```

```bash
pytest --tach-verbose
```

```bash
pytest -p no:tach
```

--------------------------------

### Tach Layered Architecture Configuration

Source: https://github.com/tach-org/tach/blob/main/docs/usage/layers.md

Defines layers and module dependencies for a 3-tier architecture. Use this TOML configuration to structure your project's layers and module relationships.

```toml
layers = [
  "ui",
  "commands",
  "core"
]

[[modules]]
path = "tach.check"
layer = "commands"

[[modules]]
path = "tach.cache"
depends_on = ["tach.filesystem"]
layer = "core"

[[modules]]
path = "tach.filesystem"
depends_on = []
layer = "core"
```