Solving Git error – refusing to update checked out branch: refs/heads/master (4 solutions)

The Problem

Experiencing errors while working with Git can be frustrating, especially when they prevent you from pushing your changes to a repository. One such common error is “refusing to update checked out branch: refs/heads/master” which typically occurs when trying to push updates to a non-bare repository on a server that has an active working directory. In this post, we will explore several methods to resolve this issue and ensure a smooth workflow with Git.

Let’s Fix It

Solution 1: Convert to a Bare Repository

One potential solution is converting the central repository to a bare repository.

1. First, ensure no one is actively working in the repository.
2. On the server hosting the Git repository, navigate to the repository’s directory.
3. Rename the repository to indicate it will be a bare repository (by convention it ends with .git).
4. Execute git config --bool core.bare true to convert it into a bare repository.
5. Remove the working directory files if present.

Example:

$ mv project project.git
$ cd project.git
$ git config --bool core.bare true
$ git push origin master
$ rm -rf ./*

Note that converting to a bare repository means there will be no working directory. This is perfect for a central repository that you are pushing to because a bare repository is not meant to have a working copy of your files, reducing the risk of conflicts with a local working directory.

Solution 2: Push to a Different Branch

Instead of pushing directly to the master branch, create a different branch for the push.

1. On your local machine, create a new branch.
2. Push your changes to the new branch on the remote server.
3. On the server, merge the changes from the new branch to the master branch.

Example:

$ git checkout -b new-branch
$ git push origin new-branch
# On the server
$ git checkout master
$ git merge new-branch

Pushing to a different branch and then manually merging reduces error chances and allows better control over the master branch. However, it requires server access to perform the merge, which might not always be convenient or possible.

Solution 3: Use –force With Caution

Using --force to disregard the error and push may seem like a solution, though it should be done with caution.

1. Ensuring no one is making changes to the repository at the same time.
2. Using the force option on push.

Example:

$ git push --force origin master

This can override changes in the server’s working directory, so it’s important to be sure that the force push does not result in work being lost. This approach is not recommended in a collaborative environment unless you are certain of the consequences.

Solution 4: Change Repository Hooks

Another method involves changing server-side hooks that reject pushes to checked out branches.

1. Access the server and navigate to the repository’s hooks directory.
2. Edit or remove the hook causing the error.
3. Attempt to push again after modifications.

Example:

$ cd project/.git/hooks/
$ # Edit or remove the update hook
$ git push origin master

Modifying hooks can be a good solution if you understand how they work and the security or workflow implications of changing them. This approach is only recommended for those with experience in managing Git hooks.

Final Words

While encountering the error “refusing to update checked out branch: refs/heads/master” can be disruptive, there are several strategies to tackle this problem effectively. Each solution has benefits and limitations, and the best choice depends on the particular workflow and collaboration needs of your team.