fest_commit.md

fest commit

Create git commit with task reference

Synopsis

Create a git commit with the festival/task ID embedded in the message.

Requires festival context: either run from inside a festival directory, a linked project directory (see 'fest link'), or use --festival to specify one.

The fest commit command wraps git commit and automatically:

1. Stages changes and prepends the festival reference to the commit message
2. Creates a camp root commit for festival-scoped files (task docs, progress, state)

When a festival or sequence has a linked project, up to two commits are created even when this command is run from inside the festival:

• Project commit: stages all project changes (skipped when the project is clean)
• Camp root commit: stages only festival directory, .campaign/fest/, festivals/.festival/.state/, and the submodule pointer

The sequence's fest_working_dir is preferred over the festival navigation link and legacy fest.yaml project_path. A festival with no linked project creates one camp root commit containing only festival-scoped files (not git add -A).

Use --no-root to skip the camp root commit. Use --no-tag to suppress all generated camp and festival reference tags. Camp's commit.disable_commit_tags setting also applies: local camp settings replace the global commit settings. Tags are enabled by default.

Reference format: [FE-{id}]

• FE: Festival component identifier
• {id}: Task ref (FEST-123456) or festival ID (e.g., CS0001)

Optional position segments: [FE-{id}-PH-{phase}-SQ-{sequence}] PH- and SQ- are additive: they record the phase and sequence the commit belongs to, and appear only when that position is unambiguous. The current directory decides it; otherwise the single in-progress sequence does. Parallel sequences leave both segments off, and SQ- is never emitted without PH-.

Detection priority:

1. Explicit --task flag value
2. Task fest_ref from current directory (if inside festival task)
3. Explicit --festival flag (path, name, or ID)
4. Festival ID from fest.yaml metadata

Examples:

  fest commit -m "Implement feature"
  # In linked project or sequence → [FE-CS0001] Implement feature
  # In festival task              → [FE-FEST-123456] Implement feature

  fest commit --task FEST-234567 -m "Related work"
  # → [FE-FEST-234567] Related work

  fest commit --festival OA0001 -m "Work from unlinked dir"
  # → [FE-OA0001] Work from unlinked dir

  fest commit -m "Update scaffold"
  # Inside 001_IMPLEMENT/02_camp_pilot → [FE-CC0008-PH-001-SQ-02] Update scaffold

  fest commit --no-tag -m "No reference"
  # → No reference

  fest commit --stage=false -m "Only commit staged"
  # Skip auto-staging, commit only what's already staged

  fest commit --auto-write
  # Run the configured camp commit-message hook from the target repo

fest commit [flags]

Options

      --auto-write        run configured commit message writer
      --commit-large      commit over-threshold files instead of keeping them out of git
      --commit-nested     commit undeclared nested git repositories as gitlinks instead of keeping them out of git
      --festival string   festival path, name, or ID (overrides auto-detection)
  -h, --help              help for commit
      --json              output result as JSON
  -m, --message string    commit message (required unless --auto-write)
      --no-root           skip camp root commit (project commit only)
      --no-tag            don't prepend camp or festival reference tags
      --stage             auto-stage all changes before commit (default true)
      --task string       task reference ID to use (e.g., FEST-123456)

Options inherited from parent commands

      --config string   config file (default: ~/.obey/fest/config.json)
      --debug           enable debug logging
      --no-color        disable colored output
      --verbose         enable verbose output

SEE ALSO

• fest - Festival Methodology CLI - goal-oriented project management for AI agents