How to fix remote: error: refusing to update checked out branch: refs/heads/main in Git

First, check if the remote repository is bare or non-bare. SSH into the remote server and run:

cd /path/to/repo
git rev-parse --is-bare-repository

If it returns false, the repository is non-bare and has a working directory. This is the root cause of the error.

You can also check by looking for a .git folder:
- Non-bare repository: Has a .git subdirectory and checked-out files
- Bare repository: Contains Git data directly (objects, refs, HEAD) without a working directory

If this repository is meant to be a central server that receives pushes, convert it to bare. On the remote server:

cd /path/to/repo
git config --bool core.bare true

Then remove the working directory files (keep them backed up if needed):

# First, back up if you have uncommitted work
cp -r . ../repo-backup

# Remove working directory files, keeping .git
rm -rf !(*.git)
# Or move everything from .git to the repo root
mv .git/* .
rm -rf .git

For a cleaner approach, create a fresh bare clone:

cd ..
git clone --bare repo repo.git
# Then update your remote URL to point to repo.git

If you need to keep the non-bare repository (e.g., for deployment), switch the remote to a different branch. SSH into the remote and run:

cd /path/to/repo
git checkout -b temp-branch
# Or checkout an existing branch
git checkout develop

Now you can push to main because it's no longer checked out. After pushing, you can switch back:

git checkout main

This is a temporary workaround—consider using a deployment branch or proper CI/CD instead.

Git 2.3.0 introduced a safer way to push to checked-out branches. On the remote repository, run:

git config receive.denyCurrentBranch updateInstead

This tells Git to update both the branch AND the working directory when receiving a push. The working directory will be updated to match the pushed content if it's clean.

Important caveats:
- This only works if the remote working directory is clean (no uncommitted changes)
- If there are uncommitted changes, the push will still be rejected
- This is safe for deployment scenarios but not for repositories with active development

If you can't modify the remote configuration, push to a different branch:

git push origin main:deploy-staging

Then SSH into the remote and merge:

cd /path/to/repo
git merge deploy-staging

This is useful when you don't have admin access to change the remote's Git configuration.

When setting up a new remote repository that will receive pushes, always create it as bare:

git init --bare /path/to/repo.git

Or clone an existing repository as bare:

git clone --bare https://github.com/user/repo.git

Bare repositories:
- Have no working directory or checked-out files
- Can receive pushes to any branch without restrictions
- Are the standard for Git servers (GitHub, GitLab use bare repos)
- Convention: name them with .git suffix (e.g., myproject.git)