Git: Troubleshooting & Recovery

Git is a powerful version control system, but users often encounter errors that can disrupt workflow. Here are some of the most common Git errors, why they happen, and step-by-step solutions to resolve them:

• fatal: not a git repository (or any of the parent directories): .git
  • Cause: You are running a Git command outside of a Git repository.
  • Solution:
    1. Navigate to the correct project directory containing the .git folder.
    2. If the directory is not a repository, initialize it with git init.
• merge conflict in <file>
  • Cause: Multiple contributors have edited the same lines in a file, causing a conflict during merge.
  • Solution:
    1. Open the conflicted file and look for conflict markers (<<<<<<<, =======, >>>>>>>).
    2. Edit the file to resolve the differences.
    3. Save the file, then run git add <file>.
    4. Commit the resolution with git commit.
• fatal: Unable to create '.git/index.lock': File exists
  • Cause: A previous Git process did not exit cleanly, leaving a lock file.
  • Solution:
    1. Remove the lock file by running rm .git/index.lock in your repository directory.
    2. Retry your Git command.
• You are in 'detached HEAD' state
  • Cause: You have checked out a specific commit instead of a branch.
  • Solution:
    1. To save your work, create a new branch: git checkout -b <branch-name>.
    2. Or return to a branch: git checkout main (or your branch name).
• error: failed to push some refs to ...
  • Cause: Your local branch and the remote branch have diverged.
  • Solution:
    1. Pull the latest changes: git pull --rebase origin main (replace main with your branch if needed).
    2. Resolve any conflicts if prompted.
    3. Push your changes again: git push.
• remote: Invalid username or password. fatal: Authentication failed
  • Cause: Your credentials are incorrect or expired.
  • Solution:
    1. Update your credentials in your system credential manager or cache.
    2. If using tokens, generate a new token and use it as your password.
• Updates were rejected because the remote contains work that you do not have locally
  • Cause: The remote repository has new commits that are not present in your local branch.
  • Solution:
    1. Pull the latest changes: git pull.
    2. Resolve any conflicts if they appear.
    3. Push your changes after resolving: git push.

When troubleshooting Git issues, a handful of commands can help you quickly diagnose and resolve problems. Below are the most essential commands, each with a step-by-step explanation:

• git status
  • Purpose: Shows the current state of your working directory and staging area.
  • How to use:
    1. Run git status in your repository directory.
    2. Review which files are staged, unstaged, or untracked.
• git log
  • Purpose: Displays the commit history.
  • How to use:
    1. Run git log to see all commits.
    2. For a concise view, use git log --oneline.
• git diff
  • Purpose: Shows differences between files or commits.
  • How to use:
    1. Run git diff to see unstaged changes.
    2. Use git diff --staged to see staged changes.
• git reset --hard
  • Purpose: Discards all local changes in your working directory.
  • How to use:
    1. Run git reset --hard to revert to the last commit.
    2. Warning: This will erase all uncommitted changes.
• git stash
  • Purpose: Temporarily saves changes that are not yet ready to be committed.
  • How to use:
    1. Run git stash to save your changes.
    2. Use git stash apply to re-apply the stashed changes later.
• git checkout -- <file>
  • Purpose: Restores a file to its last committed state.
  • How to use:
    1. Run git checkout -- <file> to discard changes in a specific file.
• git reflog
  • Purpose: Shows a log of all reference updates (useful for recovering lost commits).
  • How to use:
    1. Run git reflog to see recent updates to HEAD and branches.
    2. Use the listed commit hashes to recover previous states.
• git cherry-pick <commit_hash>
  • Purpose: Applies a specific commit from another branch or location.
  • How to use:
    1. Run git cherry-pick <commit_hash> to apply the changes from that commit.
• rm .git/index.lock
  • Purpose: Removes the lock file if Git is stuck due to a previous process.
  • How to use:
    1. Run rm .git/index.lock in your repository directory.

Even experienced Git users can encounter situations where data appears lost or mistakes disrupt progress. Here are the most common Git recovery scenarios and step-by-step solutions for each:

• Recovering Lost Commits
  • Scenario: You accidentally deleted or reset a commit and need to get it back.
  • Solution:
    1. Run git reflog to view a log of all recent changes to HEAD.
    2. Find the commit hash (SHA) of the lost commit from the reflog output.
    3. Restore the commit:
       • To move your branch pointer back: git reset --hard <commit-hash>
       • Or, to create a branch at the lost commit: git branch recover-branch <commit-hash>
• Undoing a Faulty Merge
  • Scenario: A merge introduced errors or broke your code.
  • Solution:
    1. Identify the merge commit using git log or git reflog.
    2. To revert the merge (without rewriting history), run:
       git revert -m 1 <merge-commit-hash>
    3. This creates a new commit that undoes the changes from the merge.

    Tip: Use -m 1 to specify the mainline parent (usually your main branch).

• Restoring Deleted Files
  • Scenario: You deleted a file and need to bring it back.
  • Solution:
    1. If the file was deleted but not yet committed, run:
       git restore <filename>
    2. If the deletion was already committed:
       1. Find the commit before the file was deleted using git log -- <filename>.
       2. Restore the file from the previous commit:
          git checkout <commit-hash>^ -- <filename>

Following proven Git best practices can help you avoid common pitfalls, reduce errors, and keep your workflow smooth. Here are essential guidelines, explained step by step:

• Commit Often and Make Commits Small
  • Why: Small, frequent commits make it easier to track changes, find bugs, and roll back mistakes.
  • How:
    1. Work in logical increments and commit after each significant change.
    2. Keep each commit focused on a single task or fix.
• Write Clear, Descriptive Commit Messages
  • Why: Good messages help you and your team understand the history and reasoning behind changes.
  • How:
    1. Summarize what and why, not just what changed.
    2. Use the imperative mood (e.g., "Add login validation").
• Use Branches for Features and Fixes
  • Why: Branches isolate new work, keeping the main branch stable and reducing the risk of breaking code.
  • How:
    1. Create a new branch for each feature or bugfix: git checkout -b feature/your-feature
    2. Merge back to main only after thorough testing and review.
• Pull Before You Push
  • Why: Ensures your local branch is up to date and minimizes merge conflicts.
  • How:
    1. Before pushing, run git pull to fetch and merge remote changes.
• Review Changes Before Committing
  • Why: Prevents accidental commits of unwanted or incomplete changes.
  • How:
    1. Use git diff and git status to review changes.
• Use .gitignore to Exclude Unnecessary Files
  • Why: Keeps your repository clean and avoids tracking sensitive or irrelevant files.
  • How:
    1. Create and maintain a .gitignore file at the start of your project.
    2. Regularly update it as new file types or tools are added.
• Clean Up Old Branches
  • Why: Prevents repository clutter and confusion over which branches are active.
  • How:
    1. After merging, delete feature branches locally and remotely.
• Collaborate with Pull Requests and Code Reviews
  • Why: Encourages team review, catches mistakes early, and improves code quality.
  • How:
    1. Open a pull request for each completed feature or fix.
    2. Request feedback and approval from teammates before merging.
• Protect Main Branches
  • Why: Prevents accidental changes and enforces quality standards.
  • How:
    1. Enable branch protection rules and required reviews on main branches.
• Tag Releases
  • Why: Tags mark important points in history (like releases) for easy reference and rollback.
  • How:
    1. Use git tag v1.0.0 to mark a release.

Understanding Git’s core terminology is essential for troubleshooting and recovery. Here’s a quick reference to the most common default terms you’ll encounter in Git, with concise definitions and examples:

• master / main
  • Definition: The default branch name created when you initialize a new repository. Many new projects use main as the default instead of master.
  • Example: git checkout main
• origin
  • Definition: The default name for the remote repository from which you cloned your local repository.
  • Example: git push origin main
• HEAD
  • Definition: A reference to the current commit or branch your working directory is based on. Usually points to the latest commit on your current branch.
  • Example: git log --oneline (the top entry is HEAD)
• HEAD^
  • Definition: The parent commit of HEAD (one commit before the current one).
  • Example: git checkout HEAD^
• HEAD~n
  • Definition: The n-th ancestor of HEAD (for example, HEAD~2 is two commits before the current one).
  • Example: git checkout HEAD~3
• branch
  • Definition: A parallel version of the repository, used to develop features or fixes independently from the main line of development.
  • Example: git branch feature/login
• commit
  • Definition: A snapshot of your changes in the repository’s history.
  • Example: git commit -m "Add login feature"
• remote
  • Definition: A version of your repository hosted on another server (often on the internet).
  • Example: git remote -v
• upstream
  • Definition: The default branch that your branch tracks and pulls from, usually on a remote repository.
  • Example: git push --set-upstream origin main
• index (staging area)
  • Definition: The area where changes are prepared before committing to the repository.
  • Example: git add file.txt (adds file to the index)
• working directory
  • Definition: The local directory on your computer where you make changes to files tracked by Git.
  • Example: Editing files in your project folder before staging or committing.
• tag
  • Definition: A marker for a specific commit, often used to mark releases.
  • Example: git tag v1.0