Commit Message

Conventional Commit Message Creation

Create properly formatted conventional commit messages following project standards with line length validation and required trailers.

Purpose

Generate commit messages that:

• Follow conventional commits format (type(scope): description)
• Use component names or GitHub issue numbers as scope
• Respect line length limits (50 for subject, 72 for body)
• Include required trailers (Signed-off-by, Assisted-by)
• Match Tekton commit message standards

Quick Workflow

1. Analyze changes: Run git status and git diff to understand modifications
2. Determine scope: Use component name from changed files, or GitHub issue number if available
3. Generate message: Create conventional commit message with proper formatting
4. Add trailers: Include Signed-off-by and Assisted-by trailers
5. Confirm with user: Display message and wait for approval before committing

CRITICAL: Never commit without explicit user confirmation.

Conventional Commit Format

Structure

<type>(<scope>): <description>

[optional body]

Signed-off-by: <name> <email>
Assisted-by: <Model name> (via <Tool>)

Type Selection

Choose the appropriate commit type based on changes:

For complete type reference, see references/commit-types.md.

Scope Rules

Priority 1: Component from changed files

Analyze staged files to identify the primary component:

git diff --cached --name-only

Priority 2: GitHub issue number (optional)

If the work is tracked in a GitHub issue and the user provides one, it can be used as the scope:

# Branch: fix-123-log-race
# Scope: #123 or component name
# Result: fix(log): resolve streaming race condition

Fixes #123

Add Fixes #NNN or Closes #NNN in the commit body (not the scope) — this is the standard GitHub convention for auto-closing issues.

Priority 3: Ask user

If changed files span multiple components or scope is unclear, ask the user which component is the primary focus.

Line Length Requirements

Subject Line

• Target: 50 characters maximum
• Hard limit: 72 characters
• Format: type(scope): description counts toward limit
• Tips: Use present tense, no period at end

# Good (40 chars)
feat(pipeline): add start --dry-run

# Too long - exceeds 72 char hard limit
feat(pipeline): add comprehensive dry-run support with preview output for pipeline start command

Body

• Wrap at 72 characters per line
• Blank line required between subject and body
• Content: Explain why, not what (code shows what)
• Format: Wrap manually or use heredoc in git commit

feat(pipeline): add start --dry-run

Add dry-run flag to pipeline start command that previews the
PipelineRun YAML without creating it. Useful for validating
parameters and workspace bindings before submission.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)

Required Trailers

Signed-off-by

Always include: Signed-off-by: <name> <email>

This certifies the Developer Certificate of Origin (DCO) — required by tektoncd upstream.

Detection priority order:

1. Environment variables: $GIT_AUTHOR_NAME and $GIT_AUTHOR_EMAIL
2. Git config: git config user.name and git config user.email
3. If neither configured, ask user to provide details

echo "$GIT_AUTHOR_NAME <$GIT_AUTHOR_EMAIL>"
git config user.name
git config user.email

If neither is configured, ask the user to provide their name and email.

Assisted-by

Always include: Assisted-by: <model-name> (via <Tool>)

Format examples:

Assisted-by: <Model name> (via <Tool>)

Use the actual model name (Claude Sonnet 4.5, Claude Opus 4.5, etc.).

User Confirmation Requirement

CRITICAL RULE: Always ask for user confirmation before executing git commit.

Confirmation Workflow

1. Generate the commit message following all rules above
2. Display the complete message to the user with separator
3. Ask: "Should I commit with this message? (y/n)"
4. Wait for user response
5. Commit only if user confirms (yes/y/affirmative)

Example Interaction

Generated commit message:
---
feat(pipeline): add JSON output support

Add --output=json flag to pipeline list and describe commands.
Uses the existing formatted package JSON helpers.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
---

Should I commit with this message? (y/n)

Wait for user response before proceeding.

Commit Execution

Use heredoc format for proper multi-line handling:

git commit -m "$(cat <<'EOF'
feat(pipeline): add JSON output support

Add --output=json flag to pipeline list and describe commands.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
EOF
)"

Never use:

• --no-verify (skips pre-commit hooks)
• --no-gpg-sign (skips signing)
• --amend (unless explicitly requested and safe)

Complete Examples

Feature with component scope

feat(pipeline): add start --dry-run

Add dry-run flag to pipeline start command that previews the
PipelineRun YAML without creating it on the cluster.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)

Bug fix closing a GitHub issue

fix(log): resolve concurrent streaming panic

Prevent nil pointer dereference when multiple containers stream
logs simultaneously during a TaskRun.

Fixes #789

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)

Documentation update

docs(AGENTS.md): update architecture conventions

Add command tree structure and clarify golden-file testing
rules for contributors.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)

Breaking change

feat(cli)!: remove deprecated --namespace flag

Remove the deprecated short-form --namespace flag from all
commands. Use -n instead. Deprecated since v0.30.

BREAKING CHANGE: Removed --namespace long flag from all
commands. Use -n or --ns instead.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)

Validation Rules

Every commit message must pass these checks:

1. Subject line format: Must match type(scope): description (conventional commits)
2. Subject line length: Target 50 chars, hard limit 72 chars
3. No trailing punctuation: Subject must not end with . ! ? , : ; (exception: ! for breaking changes like feat!:)
4. No trailing whitespace: On any line
5. Blank line after subject: Required before body text
6. Body line length: Wrap at 72 characters per line
7. Valid commit type: Must be one of: feat, fix, docs, style, refactor, test, chore, build, ci, perf, revert
8. Signed-off-by trailer: Required — Signed-off-by: Name <email>
9. Assisted-by trailer: Required when AI assists — Assisted-by: <Model name>
10. Trailer spacing: Blank line before trailers, no blank lines between them, no trailing blank lines

Format standards

Follow Tekton commit message standards:

• Conventional commit format (type(scope): description)
• Subject line: target 50 characters, hard limit 72
• Body lines wrapped at 72 characters
• Required Signed-off-by trailer (DCO)
• No trailing punctuation on the subject

Auto-Detection Summary

When generating commit messages:

1. Run git status (without -uall flag)
2. Run git diff for staged and unstaged changes
3. Identify primary component from staged file paths
4. If scope unclear, ask user
5. If user mentions a GitHub issue number, add Fixes #NNN to body
6. Analyze staged files to determine commit type
7. Generate appropriate scope and description
8. Detect author info from environment variables or git config
9. Ensure subject line is ≤50 characters (max 72)
10. Wrap body text at 72 characters per line
11. Add required trailers (Signed-off-by and Assisted-by)
12. Format according to conventional commits standard
13. Display message and ask for user confirmation
14. Only commit after receiving confirmation

Additional Resources

For detailed information:

• references/commit-types.md - Complete commit type reference with descriptions
• references/trailer-detection.md - Author detection logic and priority order

Source: tektoncd/cli — distributed by TomeVault.