How To Fix A Stuck GitHub Push

• Introduction
• Diagnosing the Issue
• Cause of the Issue
• Solution
  • Step 1. Checking the Commit Log
  • Step 2. Reset the Commit to the Last Pushed Commit
  • Step 3. Add the Files
  • Step 4. Commit the Files
  • Step 5. Push the Files
  • Step 6. Rinse and Repeat
• Conclusion
• References

Introduction

Recently I had an issue where a commit I was pushing to GitHub just seemed to be stuck in VS Code. It would just show the progress bar going from left to right, with the timer icon showing on the source control icon.

Diagnosing the Issue

Using various tools, I couldn't find a reason for the issue occurring. The output for the push in VS Code showed nothing and the git log command just showed the commit as being there but as the head hadn't moved, it wasn't pushed to GitHub. Also, checking the commit history on the GitHub repository in a browser showed no sign of the commit.

I attempted to close VS Code, reopen it and then perform the push again thinking it might have just gotten stuck in the aether of the interwebs but it happened again.

Switching to the terminal (not the one in VS Code) and doing a git push from there resulted in the same behavior.

Nothing was showing as being at fault. Downdetector showed GitHub had no reported issues and it wasn't VS Code's source control extension at fault.

Cause of the Issue

So, what was the issue and what was the solution?

I narrowed the issue down to it being too many files, specifically images, being pushed at any one time. I've done commits and pushes with many source code files before but not with a lot of images.

Now, these image (PNG) files were not huge in size (50KB - 150KB) so way below the maximum size for GitHub but they just would not push.

Solution

The solution I came up with is as follows.

Note: Although this is targeted at GitHub, there is no reason why it wouldn't work for other git-based repository providers, such as AWS CodeCommit, Azure DevOps or GitLab to name just a few.

Step 1. Checking the Commit Log

Disclaimer: If you have any commits pending a push, they will be lost.

Also, please make a backup copy of your files prior to starting this. Better safe than sorry as they say.

With that being said, first open up a terminal using the app of your choice. Next, cd to the directory where your git repository is on your local machine.

Next, run:

git log

The output will be a list of commits, similar to the below.

Step 2. Reset the Commit to the Last Pushed Commit

Now that you can see the list of commits, the next step is to reset the commit head to a last-know good commit. Typically, the last-know good commit will have (origin/main) next to a commit ID. You need to highlight and copy the number. An example of a commit ID is shown in the below image, highlighted in blue.

Once you have that number copied, you can now run the reset command to take the local repository back to that commit which will then clear out any commits that were made after it.

git reset commit-id

An example is shown below.

Once the reset has been done, the commits after that commit ID will disappear. For example, the below image shows that the commit for "Added images and notebook" is now removed.

The commit that was causing the problem will still be visible in the local commit list when you run git reflog but when you push the commit, those commits will not be pushed and are effectively lost as they will not show on the GitHub history.

Step 3. Add the Files

Now that the commit that was causing the issue has been cleared, it is now time to try committing and pushing again. This is where the fix for the issue is.

The solution is to break up each commit into smaller batches of around five files, push that commit and then move onto the next one. When moving onto the next one, you can try to increase the number of files each time until the issue occurs again. At that point, just go back to step one and carry on with a smaller number of files.

First, let's take a look at the list of files that are not committed / tracked.

git status

The list of files that are not committed / tracked are listed in red text.

Now that we know which files need to be committed, the next step is to add five of those files to be tracked and added to the next commit. To do this, use the git add command. For example:

git add assets/images/2-2-1.png assets/images/2-3-1.png assets/images/2-4-1.png assets/images/3-1-1.png assets/images/3-2-1.png

Step 4. Commit the Files

Now that the files have been added, the next step is to create a commit. There will be nothing different to do here that you normally would do.

git commit -m "Change message to something suitable"

What you could do is use the same commit message for each commit or use a different one for each batch.

Step 5. Push the Files

Lastly, perform a push of the commit to GitHub as normal.

git push

If you then run git log again, the origin/main should now be next to HEAD -> main (or the name of the branch you are using). For example:

Step 6. Rinse and Repeat

Once the commit has been pushed successfully to GitHub, repeat steps two to five until all of the files have been pushed to GitHub.

Conclusion

This was a strange issue that has occurred for me a couple of times and each time I managed to resolve the stuck push with the above solution.

If you have any other ways to resolve this issue, please feel free to leave your suggestion(s) in the comments.

Thank you for reading and have a nice day!

References

Git reset documentation

Git reset of local commit

Comments

[jordanaf808]

I had a similar issue, although the changes I was pushing were very small. I reset back to a known good commit and tried to push it to remote, but it wouldn't let me because there were remote changes I needed to pull first. After pulling those changes (which wasn't a problem), I was able to push up my local changes.

[inchworks]

Thanks - this cleared the stuck push to GitHub on my MacBook M1. I don't think git should hang in this way with modest file sizes, but I see unresolved reports of this problem on Apple silicon. Were you using an M1 Mac?

[dev_neil_a]

It sucks that it hangs like it does without any kind of error or warning in the logs.

In terms of the machine I was / am on, it's an Intel-based Macbook Pro. I have had this issue on multiple platforms before so it's not an Apple Silicon specific issue.

[inchworks]

That's awkward. I'm building a personal website using Hugo deployed via GitHub to a free Vercel account. So far it's gone well, but I planned to include a photo gallery. If I can't push photos to GitHub reliably, then that part of the project is a non-starter.

[Hatem Soliman]

Yeah M2 here

[Brandon Michael Hunter]

Thank for sharing. I had a similar experience with my django app and the problem was that I was trying to save my ".venv" folder into github. Once I added my ".venv" to my gitignore file, then I was successful for posting my changes to github.

Thanks again.

[Jakub T. Jankiewicz]

You don't need to use git log and copy the hash to remove last commit. You can use:

git reset HEAD~1

This will do the same.

[Julia 👩🏻‍💻 GDE]

You saved my life! 🙏

Faced the same problem using MacBook Air M1 macOS Venture v13.1 when trying to push img created with R Studio.

Thank you for this detailed explanation on how to fix the problem.

[dev_neil_a]

👍👍

I'm glad it was useful and solved your problem. It is always images that cause this problem everytime!!

[Hatem Soliman]

My solution that I came up with was to do
git push --all origin

[John Moses]

Thanks for such detailed problem solving approach. It has helped me solve a two-weeks old problem.
Thank you