bug(sync): normalize GitLab blob SHA and commit revision semantics

[ClaudiaFang]

Priority

P0 — sync correctness

Problem

GitLab exposes multiple identifiers with different meanings, including blob IDs and commit revisions. The current sync model may treat last_commit_id, tree entry id, and lastSyncedSha as interchangeable.

This can produce false remote-conflict detection across workflows, for example:

single pull stores commit SHA
→ local file changes
→ batch push compares against blob SHA
→ identifiers differ even when the remote blob is unchanged

Plan

• Define GitFile.sha as the remote blob/content identity across all providers.
• Use GitLab blob_id for file content identity.
• Store commit revision / optimistic-lock identity in a separate field when required.
• Audit single push/pull, batch push/pull, move, delete, and conflict detection for mixed SHA semantics.
• Add migration handling for existing metadata if stored identifiers cannot be reused safely.
• Add cross-flow regression tests.

Required regression scenario

single pull
→ local edit
→ batch push
→ no false remote conflict

Acceptance criteria

• Blob identity and commit revision have explicit, separate types and fields.
• GitLab behavior is consistent between getFile, tree listing, and batch operations.
• Cross-flow tests cover single/batch transitions.
• Existing GitHub and Gitea behavior remains unchanged.

[ClaudiaFang]

Manual validation plan for #101 / PR #113

Record this before merge so the same scenarios can later be promoted into the real-provider E2E suite tracked by #57.

Goal

Validate the GitLab identity split against a real GitLab repository, especially upgrade behavior from legacy metadata written by plugin 1.5.2.

The important contract is:

GitFile.sha      = blob/content identity
GitFile.revision = GitLab last_commit_id used for optimistic locking

Legacy metadata may contain last_commit_id in lastSyncedSha; successful sync should lazily migrate it back to blob SHA.

Scenario 1 — legacy single pull → batch push, no false conflict

1. Use plugin 1.5.2 against a disposable GitLab project.
2. Create test.md remotely with content version 1.
3. In Obsidian 1.5.2, refresh and perform a single-file pull of test.md.
4. Confirm .obsidian/plugins/git-file-sync/data.json now contains syncMetadata.test.md.lastSyncedSha.
5. Optionally verify the value is the file's last commit identity rather than its blob identity:

git log -1 --format=%H -- test.md
git rev-parse HEAD:test.md

6. Keep the existing data.json; replace the plugin build with PR fix: GitLab sha/revision semantics for optimistic locking #113.
7. Modify the local file to version 2 local; do not change the remote.
8. Refresh, select the file, and perform a batch/selected push.

Expected:

• file is classified as modified;
• no conflict modal appears;
• push succeeds;
• GitLab content becomes version 2 local.

This is the required regression:

legacy single pull
→ local edit
→ batch push
→ no false conflict

Scenario 2 — metadata self-heals to blob SHA

After Scenario 1 succeeds:

1. Inspect syncMetadata.test.md.lastSyncedSha in data.json.
2. Fetch the repository and compare:

git rev-parse HEAD:test.md
git log -1 --format=%H -- test.md

Expected:

• lastSyncedSha equals git rev-parse HEAD:test.md (blob SHA);
• it does not need to equal the commit SHA.

This verifies the lazy migration from legacy commit identity to blob identity.

Scenario 3 — single-file GitLab update uses revision for optimistic locking

1. Start with local and remote synchronized.
2. Modify test.md locally only.
3. Perform a single-file push rather than batch push.

Expected:

• no false conflict;
• GitLab PUT succeeds without 400/409 optimistic-lock errors;
• remote content matches the local edit.

This specifically verifies the path:

getFile()
→ blob_id + last_commit_id
→ SyncManager
→ pushFile(existingSha, existingRevision)
→ GitLab PUT last_commit_id = revision

Batch push alone does not validate this because GitLab's batch commit flow does not use the same last_commit_id PUT path.

Scenario 4 — real concurrent modification still conflicts

1. Synchronize test.md on both sides.
2. Edit it locally to version 4 LOCAL.
3. Independently edit and commit the remote file to version 4 REMOTE.
4. Refresh and attempt to push the local file.

Expected:

• conflict is detected;
• the remote is not silently overwritten before the user resolves the conflict.

This guards against making isSameBaseline() too permissive while fixing legacy metadata compatibility.

Additional smoke checks

• create a new GitLab file and push it;
• pull a remote-only GitLab file and confirm metadata uses blob SHA;
• one GitHub create/update push smoke test;
• one Gitea create/update push smoke test.

GitHub/Gitea only receive the extra optional revision parameter in this change, so they need regression smoke coverage rather than the full GitLab identity matrix.

Promote to #57 E2E

When implementing the real-provider E2E harness in #57, automate at least these GitLab scenarios:

• legacy baseline compatibility fixture → batch push without false conflict;
• getFile() returns blob SHA + revision as distinct identities;
• single-file update succeeds using revision for optimistic locking;
• successful sync persists blob identity as the new baseline;
• true local+remote concurrent modification remains a conflict.

The E2E should independently verify remote tree/blob/commit state rather than using only GitLabService to prove its own result.

[ClaudiaFang]

🎉 This issue has been resolved in version 1.5.3 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀