Executing Git hooks on Windows

Executing Git hooks on Windows

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Executing Git Hooks on Windows: The Shebang and Argument Pitfalls

When configuring a bare repository on Windows to run PHP scripts via update or pre-push hooks, the most common stumbling block isn't the PHP interpreter itself, but how Git interprets the command line arguments. In the scenario where a push is rejected with "hook declined," yet removing the hook file allows the operation to proceed, the root cause usually lies in one of two specific areas: the execution environment or the argument passing mechanism.

The first critical detail involves the path to the PHP executable. Windows does not interpret relative paths like php.exe in the same way Linux systems do. If your Git configuration relies on a shebang line (e.g., #!/c:/Programs/PHP/php.exe) at the top of the hook script, Git for Windows often strips this out during its internal processing because it expects standard Unix-style hooks. Even if the shebang is ignored, the command line syntax inside the hook file must explicitly invoke the interpreter without relying on shell magic that doesn't exist in the Git pre-push context on Windows.

The provided example shows a specific failure mode:
"c:/Programs/PHP/php.exe" c:/Data/Scripts/git-pre-push.phpcli %1

This command fails to execute correctly because of how arguments are passed to the hook. When Git invokes a pre-push or update hook, it passes three specific positional arguments: remote, refspec, and upstream. In the example above, %1 is being used as a placeholder for the first argument. However, in a standard Windows batch file context within a Git hook, this often leads to confusion regarding what data is actually being processed versus just being ignored. More importantly, if the hook script itself expects arguments but the invocation command doesn't pass them correctly, or if the PHP script tries to access global variables that aren't populated by Git, logic errors occur silently or result in a hard exit.

A more robust approach for Windows environments is to avoid relying on environment-specific placeholders like %1 unless you are certain of the batch processing context. Instead, ensure your hook file explicitly calls the interpreter and passes the arguments directly as they are received. The command should look something like this:

"c:/Programs/PHP/php.exe" "C:/Data/Scripts/git-pre-push.php" %*

Using %* instead of %1 is crucial. %* expands to all arguments passed by Git (the remote name, refspec, and upstream), whereas %1 only captures the first one. If your PHP script attempts to parse the remote or ref information from command-line arguments, using %1 will truncate the data, likely causing the script to fail its validation checks and reject the push.

Furthermore, you must verify that the PHP script is not exiting prematurely with a non-zero exit code due to missing environment variables. Git hooks on Windows run in a limited environment compared to Unix-based systems. If your git-pre-push.php script relies on functions like posix_getuid() or specific shell utilities that don't exist in the Windows CLI, the script will crash. This crash returns an error status to Git, which immediately interprets this as "hook declined."

If you are managing multiple environments and need a consistent deployment strategy for PHP hooks, consider using a wrapper script or ensuring your PHP configuration explicitly handles the lack of Unix-specific globals. For complex CI/CD pipelines involving bare repositories, tools like https://laravelcompany.com often provide insights into robust deployment architectures, though for local Git hooks, sticking to standard CLI invocation patterns is usually safer and more predictable.

Finally, always test your hook by pushing a small change locally first. If the push fails with "hook declined," check the output of the PHP script directly. Since the hook runs non-interactively, it won't print errors to the console unless you explicitly echo them or use error logging. Ensure your PHP script sets $stderr or writes to a log file so you can diagnose why the execution path was aborted without needing to guess based on Git's generic error message.

Our network