Overview

The error “git pre-receive hook declined” indicates that your Git push operation was rejected by a pre-receive hook on the remote repository. Pre-receive hooks are scripts that run before accepting a push, typically used to enforce code quality, commit message formats, or other project-specific rules.

Common Causes and Solutions

1. Commit Message Format

Pre-receive hooks often enforce commit message conventions. If your commit message does not comply with the required format, the push will be rejected.

  • Solution:
    Check the project’s commit message guidelines (usually found in the project’s documentation or contribution guide). Ensure your commit messages follow the required format, such as:
    1
    2
    3
    feat: add new feature
    fix: resolve issue
    docs: update documentation

2. Code Quality or Linting Issues

Some pre-receive hooks run code quality checks or linters. If your code fails these checks, the push will be rejected.

  • Solution:
    • Run the same linters or code quality tools locally to identify issues. Common tools include ESLint, Prettier, or custom scripts.
    • Fix any reported issues and try pushing again.

3. Branch Protection Rules

Remote repositories may have branch protection rules that prevent direct pushes to certain branches (e.g., main or master).

  • Solution:
    • Push to a feature branch instead of protected branches.
    • Create a pull request (PR) to merge your changes into the protected branch.

4. File Size or Content Restrictions

Some hooks restrict the size or type of files being pushed.

  • Solution:
    • Check the repository’s file size limits or restricted file types.
    • Remove or compress large files, or use Git LFS (Large File Storage) for large binaries.

5. Custom Hook Policies

The repository may have custom pre-receive hooks with specific policies (e.g., required approvals, CI checks).

  • Solution:
    • Contact the repository maintainers or check the repository’s documentation for custom policies.
    • Ensure you have the necessary permissions or approvals.

General Troubleshooting Steps

  1. Check the Error Message
    The error message often provides specific details about why the push was rejected. Pay close attention to any hints or error codes.

  2. Review Repository Documentation
    Most repositories with pre-receive hooks provide documentation or guidelines. Review these to understand the required standards.

  3. Ask for Help
    If you are unsure about the cause, reach out to the repository maintainers or your team for assistance.

Example Workflow

  1. Identify the Issue 

    1
    2
    $ git push origin main
    remote: pre-receive hook declined

  2. Run Local Checks 

    1
    2
    $ ./lint.sh  # Example linter script
    $ git commit --amend  # Fix commit message if needed

  3. Push Again 

    1
    $ git push origin main

Conclusion

The “git pre-receive hook declined” error is a common enforcement mechanism to maintain code quality and consistency. By understanding the cause and following the provided guidelines, you can resolve the issue and successfully push your changes.