bible/rules/patterns/git-sync-check/contract.md

Git Sync Check

Rule

Before starting any work on a task, check whether the remote repository has commits that are not yet present locally.

Required Steps

1. Run git fetch to update remote-tracking refs without merging.
2. Check for upstream commits: git log HEAD..@{u} --oneline.
3. If the output is non-empty (there are new remote commits):
   • Stop immediately. Do not make any changes.
   • Inform the user that the remote has new commits and ask how to proceed (e.g., pull, rebase, or ignore).
4. If the output is empty, proceed with the task normally.

Rationale

Working on an outdated local state risks merge conflicts, duplicate work, and overwriting changes made by other contributors. Checking remote state first keeps the working tree aligned and prevents avoidable conflicts.

Exceptions

• Offline environments where git fetch is not possible: notify the user that the check could not be performed before proceeding.