Git Merge Troubleshooting: How to Fix Missing Files and Folders After Merging Dev into Master

Table of Contents#

1. Understanding the Merge Workflow
2. Common Causes of Missing Files/Folders After Merging
3. Step-by-Step Troubleshooting: Recovering Missing Files
   • Step 1: Verify the Issue
   • Step 2: Diagnose the Root Cause
   • Step 3: Recover Files Based on the Cause
4. Preventive Measures to Avoid Future Loss
5. Conclusion
6. References

1. Understanding the Merge Workflow#

Before diving into troubleshooting, let’s recap how Git merges work in a typical dev → master scenario.

Most teams use a workflow where:

• dev (or develop) is the "integration branch" for ongoing feature work.
• master (or main) is the "stable branch" for production-ready code.

When merging dev into master, Git combines the commit histories of both branches. It uses a "merge strategy" (default: recursive) to resolve overlapping changes. If Git encounters conflicting edits to the same file, it pauses the merge and asks you to resolve conflicts manually.

Key Note: Merges can result in three outcomes:

• Fast-forward: master simply "fast-forwards" to dev’s latest commit (no new merge commit).
• Recursive merge: A new "merge commit" is created, combining dev and master’s histories.
• Conflict: Git cannot auto-resolve changes, requiring manual intervention.

Missing files typically occur during or after conflict resolution, or due to missteps in the merge process.

2. Common Causes of Missing Files/Folders After Merging#

Missing files/folders post-merge are rarely random. Here are the most likely culprits:

Cause 1: Accidental Deletion During Conflict Resolution#

When resolving merge conflicts, it’s easy to accidentally delete file content or entire files. For example:

• You open a conflicted file, see <<<<<<< HEAD (master), ======= (dev), and >>>>>>> dev markers, and mistakenly delete the entire block (including the file’s content) instead of editing it.
• A merge tool (e.g., VS Code, GitKraken) glitches, and you click "Accept Current Change" (which deletes the dev version) without noticing the file is critical.

Cause 2: Files Deleted in dev Before Merging#

If a file/folder was intentionally or accidentally deleted in dev (e.g., via git rm or manual deletion + git commit), merging dev into master will propagate that deletion to master.

Example: A teammate deletes config.json in dev (thinking it’s obsolete) and merges dev into master—now config.json vanishes from master.

Cause 3: Incorrect Merge Strategy#

Using a non-default merge strategy (e.g., ours or theirs) can overwrite files. For example:

• Running git merge -X theirs dev tells Git to always take dev’s version of conflicting files. If dev deleted a file, master will inherit that deletion.

Cause 4: .gitignore Misconfiguration#

Files may appear "missing" if they were accidentally added to .gitignore in dev and merged into master. Git will stop tracking them, making them invisible to git status or git log.

Cause 5: Force Pushes Overwriting master#

If master was force-pushed (git push --force) after the merge, it could overwrite the merge commit, erasing files added in dev.

3. Step-by-Step Troubleshooting: Recovering Missing Files#

Let’s walk through diagnosing and fixing missing files after merging dev into master.

Step 1: Verify the Issue#

First, confirm the files are truly missing (not just untracked or ignored).

Check if Files Exist in master#

Run:

# List all files in the current directory (master branch)  
ls -la  
 
# Check Git’s tracking status  
git status  
 
# Search for the missing file explicitly  
git ls-files | grep "missing-file.txt"  

If git ls-files returns nothing for the file, it’s not tracked in master.

Check if Files Exist in dev#

The files might still exist in dev. Verify with:

# Switch to dev branch  
git checkout dev  
 
# Check for the missing file  
ls -la path/to/missing-folder  
git ls-files | grep "missing-file.txt"  

If the files exist in dev, the merge likely caused the loss. If not, they were deleted in dev before merging.

Step 2: Diagnose the Root Cause#

Use Git’s history tools to trace when and why the files vanished.

Inspect the Merge Commit#

Find the merge commit hash (look for "Merge branch 'dev' into master" in git log):

# View commit history with merge commits highlighted  
git log --pretty=oneline --merges  

Example output:

a1b2c3d Merge branch 'dev' into master  # This is the merge commit  
e4f5g6h Add new feature in dev  
...  

Use the merge commit hash (a1b2c3d) to inspect changes:

# Show what changed in the merge commit  
git show a1b2c3d  

Look for lines like deleted: path/to/missing-file.txt—this confirms the file was deleted during the merge.

Compare dev and master Before the Merge#

To see if dev deleted the file, compare the state of master before the merge with dev:

# Find the commit in master BEFORE the merge (use git reflog)  
git reflog  # Lists recent commits/branches; look for "merge" entry  
 
# Example: Suppose the merge happened at HEAD@{2}, so the pre-merge commit is HEAD@{3}  
git diff HEAD@{3} dev -- path/to/missing-file.txt  

If the output shows deleted file mode 100644, dev deleted the file.

Step 3: Recover Files Based on the Cause#

Scenario A: Files Exist in dev (Deleted During Merge Conflict)#

If the files are still in dev but missing in master, recover them by checking them out from dev:

# Checkout the missing file/folder from dev into master  
git checkout dev -- path/to/missing-file.txt  
 
# For a folder:  
git checkout dev -- path/to/missing-folder/  
 
# Commit the recovery  
git commit -m "Recover missing files from dev after merge"  

Scenario B: Files Deleted in dev (Propagated to master)#

If dev deleted the files (and you want to restore them to master), recover from master’s state before the merge:

1. Find the master commit before the merge using git reflog:

   git reflog  
   # Example output:  
   # a1b2c3d (HEAD -> master) HEAD@{0}: merge dev: Merge made by the 'recursive' strategy.  
   # 9876543 HEAD@{1}: checkout: moving from dev to master  
   # 56789ab HEAD@{2}: commit: Update readme in master  # <-- This is pre-merge master  

2. Check out the file from the pre-merge commit:

   git checkout 56789ab -- path/to/missing-file.txt  
    
   # Commit the restoration  
   git commit -m "Restore file deleted in dev from pre-merge master"  

Scenario C: Accidental Deletion During Conflict Resolution#

If you resolved a conflict and deleted the file by mistake, use git reflog to undo the merge and redo it carefully:

1. Find the commit before the merge (e.g., 56789ab from git reflog).

2. Reset master to that commit (backup first!):

   # Create a backup branch to avoid data loss  
   git branch master-backup  
    
   # Reset master to the pre-merge state  
   git reset --hard 56789ab  
    
   # Now re-merge dev, but resolve conflicts carefully  
   git merge dev  

   Use a merge tool (e.g., git mergetool) to visually resolve conflicts and ensure no files are deleted.

Scenario D: .gitignore Misconfiguration#

If files are tracked in dev but ignored in master, check .gitignore:

# Compare .gitignore between master and dev  
git diff dev master -- .gitignore  
 
# If the missing file is in .gitignore, remove it  
nano .gitignore  # Delete the line with the missing file  
 
# Re-add the file to Git tracking  
git add path/to/missing-file.txt  
git commit -m "Fix .gitignore; re-track missing file"  

4. Preventive Measures to Avoid Future Loss#

An ounce of prevention is worth a pound of recovery. Use these tips to avoid missing files in future merges:

1. Merge Frequently#

Merge dev into master (or master into dev) regularly. Smaller, incremental merges reduce conflict complexity and make deletions easier to spot.

2. Review Merges Before Committing#

After resolving conflicts, run git status and git diff --staged to check for unintended deletions. Tools like VS Code’s "Source Control" tab highlight changes visually.

3. Use git pull --rebase Instead of git pull#

Rebasing (git pull --rebase) replays your dev commits on top of master, reducing merge conflicts. It keeps history linear and makes deletions harder to hide.

4. Audit .gitignore#

Before merging, check .gitignore in dev to ensure no critical files are added. Use git check-ignore -v path/to/file to verify if a file is ignored.

5. Avoid Force Pushes on master#

Never force-push to master (git push --force) unless absolutely necessary. Use git push --force-with-lease instead, which aborts if others have pushed changes.

6. Backup Branches#

Before merging, create a backup branch (e.g., master-before-merge) to revert to if something goes wrong:

git checkout master  
git branch master-before-merge  

5. Conclusion#

Missing files after merging dev into master is stressful, but Git’s robust history tools make recovery possible. By diagnosing the root cause (conflict mishaps, deletions in dev, or .gitignore issues) and using git reflog, git checkout, and git reset, you can restore lost files.

Remember: prevention is key. Merge frequently, review changes carefully, and avoid risky operations like force pushes. With these practices, you’ll keep your master branch stable and your team’s workflow smooth.

6. References#

• Git Merge Documentation
• Resolving Merge Conflicts (GitHub Docs)
• Git Reflog: Recovering Lost Commits (Atlassian)
• .gitignore Guide (Git SCM)