Pre-flight Prevent Direct Push

Blocks direct git push commands to protected branches, enforcing Git Flow workflow with feature branches and pull requests.

When to Use This Hook

Attach this hook when you need to:

• Prevent accidental pushes directly to main or develop branches, enforcing that all changes go through pull requests
• Enforce Git Flow or GitHub Flow branching strategies by blocking push commands that bypass the review process
• Provide immediate feedback when developers attempt to push to protected branches with guidance on the correct workflow

Consider alternatives when:

• Your git hosting platform already has server-side branch protection rules that reject direct pushes
• Your team uses trunk-based development where pushing directly to main is the intended workflow

Quick Start

Configuration

Copy
name: pre-flight-prevent-direct-push
type: hook
trigger: PreToolUse
category: git

Example Trigger

Copy
git push origin main
# Hook intercepts:
# BLOCKED: Direct push to protected branch "main"

Example Output

Pre-flight Push Guard: Branch Protection Check
Command: git push origin main
Target Branch: main
Branch Status: PROTECTED
Decision: BLOCKED

Direct pushes to "main" are not allowed.
Required workflow:
  1. Create a feature branch: git checkout -b feature/my-change
  2. Push the feature branch: git push origin feature/my-change
  3. Create a pull request for review
  4. Merge via pull request after approval

Use feature/, release/, or hotfix/ branches instead.

Core Concepts

Push Prevention Overview

Aspect	Details
Trigger Point	PreToolUse on Bash commands matching git push patterns
Protected Branches	main, develop (configurable)
Detection Method	Python script parses push command for target branch
Block Behavior	Returns exit code 2 to prevent the push command from executing
Allowed Branches	feature/, release/, hotfix/* and any non-protected branch
Script Location	$CLAUDE_PROJECT_DIR/.claude/hooks/prevent-direct-push.py

Push Guard Workflow

PreToolUse (Bash with git push)
    |
    v
[prevent-direct-push.py parses command]
    |
    v
[Extract target branch from push command]
    |
    v
[Is target branch in protected list?]
    |          |
   No         Yes
    |          |
 ALLOW       BLOCK
(exit 0)   (exit 2)
              |
              v
         [Output error message with workflow guidance]
         [Suggest feature branch workflow]

Configuration

Parameter	Type	Default	Description
protected_branches	string	main|develop	Pipe-separated list of branches that cannot receive direct pushes
allowed_prefixes	string	feature/|release/|hotfix/	Branch name prefixes that are always allowed for push
block_force_push	boolean	true	Whether to also block force push (--force) to any branch
show_workflow	boolean	true	Whether to display the recommended workflow steps in the block message
timeout	integer	10	Maximum seconds for the Python script to complete validation

Best Practices

1. Commit the prevention script to version control - Place the prevent-direct-push.py script in .claude/hooks/ and commit it to the repository. This ensures all team members have the same branch protection rules without manual configuration.

2. Include develop branch in the protected list - Protecting both main and develop prevents accidental pushes to either integration branch. All changes should flow through feature branches and pull requests regardless of which integration branch they target.

3. Display clear workflow guidance on block - When a push is blocked, the error message should include step-by-step instructions for the correct workflow. This turns a blocking event into a teaching moment, especially for new team members unfamiliar with Git Flow.

4. Consider blocking force push to all branches - Force pushing rewrites history and can cause data loss for collaborators. Enable block_force_push to prevent force pushes entirely, or restrict them to personal feature branches only.

5. Test the guard with a practice push - After configuring the hook, test it by attempting git push origin main in a safe environment. Verify the block message appears correctly and provides actionable guidance before relying on it in production.

Common Issues

1. Push to main is blocked but the feature is urgent - For emergency hotfixes, the guard allows pushes to branches with the hotfix/ prefix. Create a hotfix/critical-fix branch, push to it, and create an expedited pull request. Document the emergency procedure so the team knows the escape hatch.

2. Guard does not detect push when branch is specified differently - The Python script parses git push origin main but may not catch alternative forms like git push origin HEAD:main or git push --all. Ensure the script handles all common push command variations.

3. Python script not found at expected path - The hook expects the script at $CLAUDE_PROJECT_DIR/.claude/hooks/prevent-direct-push.py. If the CLAUDE_PROJECT_DIR variable is not set or points to the wrong directory, the hook will fail. Verify the variable with echo $CLAUDE_PROJECT_DIR.