Git Hooks Integration¶

Gira provides built-in Git hooks to enhance your development workflow by automatically validating commit messages and ensuring they include ticket IDs.

Overview¶

Git hooks are scripts that run automatically during Git operations. Gira provides two main hooks:

commit-msg: Validates that commit messages include a Gira ticket ID
prepare-commit-msg: Automatically adds ticket ID templates based on your branch name

Installation¶

Quick Start¶

Install all available Gira hooks:

gira hooks install

Selective Installation¶

Install specific hooks:

gira hooks install --hook commit-msg
gira hooks install --hook prepare-commit-msg

Check Status¶

View which hooks are currently installed:

gira hooks status

Example output:

                   Git Hooks Status                   
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ Hook               ┃ Status        ┃ Type ┃ Backup ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━┩
│ commit-msg         │ ✓ Installed   │ Gira │ No     │
│ prepare-commit-msg │ ✓ Installed   │ Gira │ No     │
└────────────────────┴───────────────┴──────┴────────┘

Hook Descriptions¶

commit-msg Hook¶

This hook validates commit messages to ensure they include a Gira ticket ID.

Valid commit message formats: - feat(GCM-123): add new feature - fix: resolve issue\n\nGira: GCM-123 - [GCM-123] Update documentation - GCM-123: Quick fix

Features: - Automatically skips merge commits and fixup commits - Uses your project's ticket ID prefix - Configurable validation strictness - Clear error messages with examples

prepare-commit-msg Hook¶

This hook helps you by automatically adding ticket ID templates to your commit messages.

Features: - Extracts ticket ID from branch names (e.g., feature/GCM-123-description) - Adds a conventional commit template - Only activates for empty commit messages - Respects existing ticket IDs

Example: If you're on branch feature/GCM-123-user-auth, the hook will create:

feat(GCM-123): 

# Gira: GCM-123

Configuration¶

Configure hook behavior through your project settings:

# Enable/disable specific hooks
gira config set hooks.commit_msg_enabled false
gira config set hooks.prepare_commit_msg_enabled true

# Enable strict mode (requires conventional format)
gira config set hooks.commit_msg_strict true

# Configure automatic ticket extraction from branch
gira config set hooks.auto_ticket_from_branch true

# Set allowed commit types for strict mode
gira config set hooks.allowed_commit_types "feat,fix,docs,test,refactor"

Configuration Options¶

Setting	Default	Description
`hooks_commit_msg_enabled`	`true`	Enable commit message validation
`hooks_commit_msg_strict`	`false`	Require conventional format: `type(ID): msg`
`hooks_prepare_commit_msg_enabled`	`true`	Enable commit message templates
`hooks_auto_ticket_from_branch`	`true`	Extract ticket IDs from branch names
`hooks_allowed_commit_types`	`["feat", "fix", "docs", "style", "refactor", "test", "chore"]`	Valid types for strict mode

Uninstallation¶

Remove all Gira hooks:

gira hooks uninstall

Remove specific hooks:

gira hooks uninstall --hook commit-msg

Note: If you had existing hooks before installing Gira hooks, they will be restored from backups.

Bypassing Hooks¶

Sometimes you need to commit without validation:

# Bypass all hooks for this commit
git commit --no-verify -m "WIP: debugging"

# Or use the shorthand
git commit -n -m "WIP: debugging"

Advanced Usage¶

Strict Mode¶

Enable strict mode to enforce conventional commit format:

gira config set hooks.commit_msg_strict true

In strict mode, commits must follow:

type(TICKET-ID): description

[optional body]

[optional footer]

Custom Commit Types¶

Configure allowed commit types:

gira config set hooks.allowed_commit_types "feat,fix,docs,perf,build"

Branch Naming Conventions¶

For automatic ticket ID extraction, use branch names like: - feature/GCM-123-description - bugfix/GCM-456-fix-issue - GCM-789-quick-fix - users/john/GCM-321-feature

Troubleshooting¶

Hook Not Running¶

Check if hooks are installed:
```
gira hooks status
```
Verify hook files are executable:
```
ls -la .git/hooks/
```

Check if hooks are enabled in config:

gira config get hooks.commit_msg_enabled

Hook Preventing Commits¶

Check your commit message includes a ticket ID
Use --no-verify to bypass temporarily

Disable the hook if needed:

gira config set hooks.commit_msg_enabled false

Conflicts with Existing Hooks¶

Gira backs up existing hooks before installation. To restore:

# Uninstall Gira hooks (restores backups)
gira hooks uninstall

# Or manually restore
mv .git/hooks/commit-msg.backup .git/hooks/commit-msg

Best Practices¶

Consistent Branch Names: Use ticket IDs in branch names for automatic template filling
Meaningful Commits: The hooks ensure traceability, but write descriptive messages
Team Alignment: Ensure your team agrees on strict mode and commit conventions
Regular Updates: Keep Gira updated to get the latest hook improvements

Integration with CI/CD¶

The hooks only run locally. To enforce commit message standards in CI:

# Example GitHub Actions workflow
- name: Validate Commit Messages
  run: |
    # Check last commit
    if ! git log -1 --pretty=%B | grep -E '[A-Z]{2,4}-[0-9]+'; then
      echo "Commit message must include a Gira ticket ID"
      exit 1
    fi

Future Enhancements¶

Post-commit Hook for Status Updates¶

Based on our research, we recommend implementing post-commit hooks rather than pre-commit hooks for automatic status updates. This approach provides better user experience because:

Runs after the commit is created, avoiding interference with the commit process
Can safely update ticket status without affecting version control
More appropriate timing for workflow automation

Proposed Future Features¶

Post-commit Hook Implementation
Automatically update ticket status based on branch activity
Parse commit messages for status directives (e.g., [status:in_progress])
Configurable auto-progression rules
Branch Management Commands
gira branch create GCM-123 - Create branch and optionally move ticket to "in_progress"
Automatic status updates when creating feature branches
Integration with Git workflow
Commit Message Directives
Support inline status updates: feat(GCM-123): implement feature [status:review]
Process directives in post-commit hook
Maintain audit trail of status changes

These enhancements would provide seamless Git integration while respecting developer workflows and maintaining predictable behavior.