Don’t Panic When the Terminal Throws an Error
A bright red error message appearing right before deployment is every developer’s nightmare. I once saw a colleague nearly in tears after losing a week’s worth of code simply by typing git reset --hard.
Git is highly flexible but full of pitfalls if you don’t understand the pointer mechanism. Instead of deleting the folder and git clone-ing from scratch, learn to master it. Here are 10 of the most awkward situations and how to resolve them cleanly with a technical mindset.
Git is Actually a Time Machine
Almost nothing in Git is ever truly lost if you have committed it. Git records every movement in a hidden journal called Reference Logs (reflog). Once you have this key, you’ll find that Git is no longer an elusive system.
1. “Detached HEAD” Error – When You’re Floating in the Void
This error occurs when you git checkout a specific commit ID instead of a branch. At this point, HEAD doesn’t point to any branch name. You can still write code, but new commits won’t belong to any branch.
# Common message:
# You are in 'detached HEAD' state.Solution: If you’ve accidentally coded new features in this state, create a new branch immediately to save your work.
# Create a new branch at the current position
git checkout -b recovery-branch
# Switch back to the main branch and merge
git checkout main
git merge recovery-branch2. Push Rejected (Non-fast-forward)
You push your code and receive the message: [rejected] main -> main (fetch first). This happens when a colleague has pushed code to the server before you. Your local repository is now outdated compared to the server.
Warning: Never use git push --force in a shared project. This command will overwrite and wipe out the entire team’s commit history on the server.
Safe Solution:
# Option 1: Rebase (keeps commit history clean and linear)
git pull --rebase origin main
git push origin main
# Option 2: Traditional Merge
git pull origin main
# Resolve conflicts if any, then push3. Accidentally Committing to the Main Branch
You were supposed to work on feature-login, but you ended up coding directly on main. This is a very common situation when working in a hurry.
Solution: Move those commits to the correct branch and reset main to its original state.
You were supposed to work on feature-login, but you ended up coding directly on main. This is a very common situation when working in a hurry.
# 1. Create a new branch to keep the recent commits
git branch feature-login
# 2. Reset the main branch back (e.g., back 3 commits)
git reset --hard HEAD~3
# 3. Switch to the feature branch to continue working
git checkout feature-login4. Rescuing Data After an Accidental `git reset –hard`
This is where git reflog shines. Suppose you just accidentally deleted 5 important commits using the reset command. Don’t worry, Git still has a record of them.
git reflog
# Find the line containing the commit you just lost, e.g., ab12345
# Restore to that exact point in time
git reset --hard ab123455. Amending the Most Recent Commit Message
You just finished a commit and noticed a typo or forgot to git add a configuration file. Instead of creating a new commit that clutters the history, use --amend.
# Add the missing file
git add config.json
# Overwrite the latest commit
git commit --amend --no-edit
# If you only want to change the message content
git commit --amend -m "New and improved commit message"6. Aborting a Failed Merge or Rebase
Sometimes resolving conflicts becomes so complex that the code gets messy. You want to return to the state before the merge to rethink your approach.
# Stop immediately and return the code to its original state
git merge --abort
# Same for an ongoing rebase
git rebase --abort7. Files in .gitignore Still Being Tracked
You’ve added .env to .gitignore, but Git still reports changes every time you edit this file. This happens because the file was already cached by Git previously.
Solution: Remove the file from the cache without deleting it from the hard drive.
git rm --cached .env
git add .gitignore
git commit -m "Stop tracking environment file"8. Accidentally Committing Large Files
You accidentally commit a 500MB log file or the node_modules folder. Even if you delete it in a later commit, the file remains in the history and bloats the .git file.
Solution: Use tools like git-filter-repo or bfg. Avoid using filter-branch as it is very slow and Git now recommends against its use.
# Example using BFG to quickly remove large files
bfg --strip-blobs-with-ids-larger-than 50M9. Quickly Renaming a Branch
Mistyping a branch name like feture-ui instead of feature-ui is very common. You can rename it locally and then update it on the server.
# Rename locally
git branch -m feture-ui feature-ui
# Delete the incorrect branch on the server and push the correct one
git push origin --delete feture-ui
git push origin feature-ui10. Case-Sensitivity Errors (Uppercase/Lowercase)
Windows doesn’t distinguish between User.js and user.js, but Linux (Server) does. This often causes deployment errors. Git sometimes fails to recognize that you’ve renamed a file from lowercase to uppercase.
Solution: Force Git to recognize the rename using the git mv command.
git mv user.js User.js
# Or configure Git to always be case-sensitive
git config core.ignorecase falseReal-world Project Experience
Working with Git is like operating a system; mistakes are inevitable. However, instead of overusing --force, prioritize safe commands.
My little tip: Before performing commands that deeply alter history, such as rebase or filter-branch, create a backup branch. If things go wrong, it only takes 5 seconds to revert to the previous state. Happy coding, and may your commits be clean and your nights free of Git errors!
