Repository Configuration

The .repo.yml file in your project root configures repository-specific behavior including custom commands, release settings, and AI commit preferences.

Quick Start

Create a .repo.yml file in your project root:

# .repo.yml
commands:
  test:
    run: npm test
    description: Run test suite

release:
  bump_strategy: smart-auto
  changelog: true
  tag_format: "v{version}"

commit:
  template: accid
  require_issue_id: false

Complete Configuration

# .repo.yml - Complete example
version: 1

# Custom commands
commands:
  test:
    run: npm test
    description: Run test suite
    env:
      NODE_ENV: test
  
  build:
    run: npm run build
    description: Build production bundle
  
  deploy:
    run: |
      npm run build
      scp -r dist/ server:/var/www/
    description: Build and deploy to production
    require_clean: true  # Fail if uncommitted changes

# Release configuration
release:
  # Version bump strategy
  bump_strategy: smart-auto  # auto | smart-auto | manual
  
  # Bump engine
  bump_engine: accid-git     # accid-git | conventional
  
  # Generate changelog
  changelog: true
  changelog_file: CHANGELOG.md
  
  # Tag format
  tag_format: "v{version}"
  
  # Hooks
  pre_release_hook: ./scripts/pre-release.sh
  post_release_hook: ./scripts/post-release.sh
  
  # Push settings
  push: true
  push_tags: true

# Commit configuration
commit:
  # AI-generated commit messages
  generate_message:
    default_provider: anthropic
    format: accid              # accid | conventional | custom (default: accid)
    rules_file: .nanx/rules.md # Optional: custom rules or @extends directive
    auto_stage: false
    max_tokens: 500
    temperature: 0.7
  
  # Commit message template (for non-AI commits)
  template: accid              # accid | conventional | simple
  
  # Require issue/ticket ID
  require_issue_id: false
  issue_pattern: "^#\\d+$"     # Regex for issue ID format
  
  # Sign commits
  sign: false
  gpg_key: ""
  
  # Pre-commit hooks
  pre_commit_hook: ./scripts/pre-commit.sh

# Branch configuration
branch:
  # Default branch
  default: main
  
  # Branch naming conventions
  naming:
    feature: "feature/{name}"
    bugfix: "bugfix/{name}"
    hotfix: "hotfix/{name}"
  
  # Protected branches
  protected:
    - main
    - develop
    - release/*

# Push configuration  
push:
  # Default push behavior
  default_remote: origin
  set_upstream: true
  force_with_lease: false

Commands

Define custom commands that can be run with nanx repo run <command>:

Basic Command

commands:
  test:
    run: npm test
    description: Run test suite

Command with Environment Variables

commands:
  test:
    run: npm test
    description: Run test suite
    env:
      NODE_ENV: test
      CI: true

Multi-line Command

commands:
  deploy:
    run: |
      npm run build
      npm run test
      scp -r dist/ server:/var/www/
    description: Build, test, and deploy

Command Options

Release Configuration

Bump Strategy

Bump Engine

Tag Format

Customize release tag format:

# Default semver with v prefix
tag_format: "v{version}"  # → v1.2.3

# No prefix
tag_format: "{version}"   # → 1.2.3

# Custom prefix
tag_format: "release-{version}"  # → release-1.2.3

Changelog

release:
  changelog: true
  changelog_file: CHANGELOG.md
  changelog_template: |
    ## [{version}] - {date}
    
    {changes}

Changelog Configuration New in v0.3.0

Enable AI-powered changelog generation:

release:
  changelog:
    enabled: true                       # Enable changelog generation
    output_dir: "change-logs"           # Directory for changelogs
    end_user_dir: "end-user"            # Subdirectory for end-user changelogs
    internal_format: "detailed"         # detailed | keep-a-changelog | conventional | commits-only | custom
    end_user_format: "detailed"         # Same options, or null to disable
    include_contributors: true          # Include contributors section
    end_user_show_contributors: true    # Show contributors in end-user changelog
    end_user_include_emails: false      # Include emails in contributors
    provider: "anthropic"               # AI provider for generation
    rules_file: ".ai/changelog-rules.md"  # Custom rules file path
    team_name: "My Team"                # Team name for end-user changelog
    issue_url_template: "https://linear.app/org/issue/{id}"
    fallback_on_ai_error: false         # Fallback to commits-only on AI error (v0.4.1+)

Changelog Format Options New in v0.3.2

Path Filtering

Control which changes appear in changelogs:

release:
  changelog_include_dependencies: true  # Include NX-detected dependencies
  changelog_include_paths:              # Additional paths to include
    - "libs/shared"
  changelog_exclude_paths:              # Paths to exclude
    - "tests/"
    - "**/*.test.ts"
    - ".github/"

Per-Project Overrides

release:
  projects:
    my-lib:
      changelog:
        internal_format: "keep-a-changelog"
        provider: "openai"
      changelog_include_dependencies: false

See Changelog Command for manual changelog generation.

Tag Message New in v0.3.0

Configure rich git tag messages:

release:
  tag_message:
    changelog_public_url_base: "https://github.com/org/repo/blob/main/CHANGELOG.md"
    contributor_format: "{name} ({email})"

Release Hooks

Run scripts before/after creating a release:

release:
  pre_release_hook: ./scripts/pre-release.sh
  post_release_hook: ./scripts/post-release.sh

Example scripts/pre-release.sh:

#!/bin/bash
# Run tests
npm test || exit 1

# Build
npm run build || exit 1

# Update version in package.json
echo "Pre-release checks passed"

Commit Configuration

Message Templates

See ACCID Format Guide for detailed format specification.

AI-Generated Commits

Nanx includes embedded ACCID and Conventional Commits format specifications. You can use these as-is, or extend them with custom project-specific rules.

Using Embedded Formats

commit:
  generate_message:
    default_provider: anthropic
    format: accid         # Use embedded ACCID format (default)
    # format: conventional  # Or use embedded Conventional Commits
    # format: custom        # Or use pure custom rules

Extending with Custom Rules

Method 1: Config-based Extension

commit:
  generate_message:
    format: accid
    rules_file: .nanx/custom-rules.md  # Appends to ACCID format

Method 2: File-based Extension with @extends

commit:
  generate_message:
    rules_file: .nanx/custom-rules.md  # File contains @extends directive

Create .nanx/custom-rules.md:

# @extends accid-commit

## Project-Specific Rules

- Include Jira ticket ID (PROJ-XXX)
- Use emoji prefixes for types
- Reference PRs in footer

Format Options

See AI Commit Workflow for complete guide.

Require Issue IDs

commit:
  require_issue_id: true
  issue_pattern: "^#\\d+$"  # Matches #123, #456, etc.

Commit Signing

commit:
  sign: true
  gpg_key: "your-key-id"  # Optional, uses git config if omitted

Pre-commit Hook

commit:
  pre_commit_hook: ./scripts/pre-commit.sh

Branch Configuration

Branch Naming Conventions

branch:
  naming:
    feature: "feature/{name}"
    bugfix: "bugfix/{name}"
    hotfix: "hotfix/{name}"
    release: "release/{version}"

Usage:

# Create feature branch
nanx r b feature/oauth-login
# → Creates: feature/oauth-login

# Create bugfix branch  
nanx r b bugfix/login-error
# → Creates: bugfix/login-error

Protected Branches

branch:
  protected:
    - main
    - develop
    - release/*

Protected branches prevent:

• Direct commits (must use PRs)
• Force pushes
• Deletion

Push Configuration

push:
  default_remote: origin
  set_upstream: true        # Auto set upstream on first push
  force_with_lease: false   # Use --force-with-lease flag

Worktree Configuration New in v0.4.0

Configure worktree behavior for automatic setup file copying and branch switching actions. Worktree config can be set at two levels:

• Local (.repo.yml): Shared with team, for common setup files
• Global (~/.nanx/repos.yml): Personal settings, per-repo overrides

Setup File Copying

Automatically copy files (like .env) when creating new worktrees:

# .repo.yml (shared with team)
worktree:
  copy_files:
    - ".env.example"        # Copy example env file
    - ".vscode/settings.json"
    - "docker-compose.override.yml"

# ~/.nanx/repos.yml (personal settings)
repositories:
  - slug: my-project
    worktree:
      copy_files:
        - ".env"            # Copy actual env with secrets
        - ".env.local"
        - "secrets/local.json"

Files from both configs are merged. Source worktree priority:

1. --copy-from <branch> flag (if specified)
2. Current worktree (when switching)
3. Default branch worktree (main or master)

Switch Action

Control what happens after creating/switching to a worktree:

# ~/.nanx/repos.yml
settings:
  on_switch_action: auto    # auto | editor | cd | none
  editor: cursor            # Editor for 'editor' action

Edit Worktree Config

# Edit global repos config
nanx config repos --global

# Edit local .repo.yml
nanx config repos --local

# Show config paths
nanx config repos --path

See Worktree Workflow for complete documentation.

Examples

Minimal Configuration

# .repo.yml
commands:
  test:
    run: npm test

release:
  bump_strategy: smart-auto
  changelog: true

Node.js Project

# .repo.yml
commands:
  test:
    run: npm test
  
  lint:
    run: npm run lint
  
  build:
    run: npm run build
  
  dev:
    run: npm run dev
    description: Start development server

release:
  bump_strategy: smart-auto
  bump_engine: conventional
  changelog: true
  tag_format: "v{version}"
  pre_release_hook: ./scripts/pre-release.sh

commit:
  template: conventional
  sign: true

Rust Project

# .repo.yml
commands:
  test:
    run: cargo test
  
  build:
    run: cargo build --release
  
  clippy:
    run: cargo clippy -- -D warnings
  
  fmt:
    run: cargo fmt --check

release:
  bump_strategy: smart-auto
  bump_engine: accid-git
  changelog: true
  tag_format: "v{version}"

commit:
  template: accid
  pre_commit_hook: ./scripts/pre-commit.sh

Validation

Validate your .repo.yml:

nanx repo config validate

Next Steps

• Release Workflow Guide
• ACCID Commit Specification
• Repository Commands
• Nanx Configuration