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. This rule assumes the repository is hosted in Gitea. Use neutral git commands for sync checks and branch management, and use Gitea terminology for server-side review flow (pull request, not merge request).

Required Steps

1. Run git fetch origin to update remote-tracking refs from the Gitea remote 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.

Gitea Workflow Notes

• Verify the remote when needed: git remote -v
• Create a task branch before changes: git checkout -b <task-branch>
• Push the branch to Gitea and set upstream: git push -u origin <task-branch>
• Open the review in Gitea as a pull request against the target branch.
• If the tea CLI is configured for the environment, it may be used for Gitea pull request actions such as:
  • tea pr list
  • tea pr create
  • tea pr checkout <number>

Forbidden Assumptions

• Do not assume GitHub-specific tooling such as gh.
• Do not use GitLab terminology such as merge request unless a project explicitly defines that workflow separately.
• Do not replace the required sync check with web UI inspection in Gitea; the local git fetch origin and git log HEAD..@{u} --oneline check remains mandatory.

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. Using Gitea-specific review terminology and examples also avoids workflow confusion in repositories that are not hosted on GitHub or GitLab.

Exceptions

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