In short only need
git pull --no-rebase
git checkout <GOOD_COMMIT_HASH> -- .
git commit
git push
That is forward recovery.
No git reset --hard was necessary.
1. What Happened (Summary)
A merge operation between the local main branch and origin/main introduced unintended changes that appeared to delete or overwrite vault files. This was caused by a merge commit that resolved conflicts incorrectly, especially involving Obsidian-generated configuration files and possibly symbolic link content.
The situation escalated because:
-
The
mainbranch was protected on GitLab (no force push allowed). -
A local hard reset moved the branch pointer backward.
-
The remote branch still contained newer commits including the problematic merge.
Result:
-
Local files were safe after reset.
-
Remote history diverged.
-
Normal push failed because history could not be rewritten.
2. Root Causes
A. Merge Conflict Resolution Error
During:
Merge remote-tracking branch 'origin/main'
Conflicts occurred in:
-
.obsidian/workspace.json -
Other vault files / symbolic link references.
Selecting the wrong side during conflict resolution can overwrite or effectively remove files.
B. Obsidian Auto-Generated Files in Git
Files such as:
.obsidian/workspace.json
.obsidian/cache/
change frequently and are not ideal for version control.
They commonly trigger unnecessary conflicts.
C. Protected Branch Policy
GitLab blocked:
git push --force
This prevented rewriting history even though local state was correct.
D. Misunderstanding Git Snapshot Model
Git stores full snapshots, not incremental edits.
Files weren’t truly “deleted” — they were replaced by another snapshot during merge.
3. Final Solution (What Actually Fixed It)
Instead of rewriting history, a forward restore commit was created.
Step-by-step recovery:
1. Sync local history with remote:
git pull --no-rebase
This aligned commit history even if files were temporarily wrong.
2. Restore files from known good commit:
Example:
git checkout <GOOD_COMMIT_HASH> -- .
This copies the snapshot of all files from that commit into the current working tree.
No history rewriting occurs.
3. Commit the restored state:
git add .
git commit -m "Restore vault after accidental merge"
This creates a new commit that fixes the problem.
4. Push normally:
git push origin main
Because history remained linear, the protected branch allowed it.
4. Why This Method Works
This is called forward recovery:
-
No history rewriting.
-
Full traceability.
-
Compatible with protected branches.
-
Safe for collaborative environments.
Git treats each commit as a complete project snapshot.
5. Risks Identified
1. Obsidian Workspace Tracking
Tracking UI state files causes unnecessary conflicts.
2. Multi-device Editing Without Pull First
Editing before pulling latest commits increases merge conflicts.
3. Symlinked Content
Symbolic links can confuse Git during merges.
4. Protected Branch Without Recovery Plan
Protected branches require forward commits instead of resets.
6. Mitigation Strategy (Recommended)
A. Update .gitignore
Add:
.obsidian/workspace.json
.obsidian/cache/
.obsidian/plugins/
This prevents recurring merge conflicts.
B. Adopt Safe Git Workflow
Before editing:
git pull
After editing:
git add .
git commit -m "update"
git push
Never skip pull on multi-device setups.
C. Avoid Auto-Merge via Plugins
Manual merge review reduces accidental overwrites.
D. Backup Strategy
Use hybrid backup:
-
Git → notes/version history
-
Cloud storage → large media
Do not rely on Git alone.
E. Branch Protection Awareness
Protected branches require:
-
Forward commits (revert/restore)
-
Not history rewrites.
Plan recovery accordingly.
7. Lessons Learned
-
Git merge issues are usually conflict resolution problems, not file loss.
-
Force push is not always allowed; forward restore commits are safer.
-
Auto-generated config files should rarely be version-controlled.
-
Understanding Git’s snapshot model prevents panic during recovery.
8. Current Status
✔ Files restored
✔ History preserved
✔ Remote synchronized
✔ Protected branch respected
Incident resolved successfully.