3.3 KiB
Repository Update Workflow
Read this reference for every Gitea repository update.
1. Resolve Inputs
Identify the clean Gitea HTTPS URL, prepared source paths, repository target paths, target branch, and commit intent. If a source-to-target mapping is ambiguous, stop and ask before writing.
2. Inspect Before Editing
Read applicable AGENTS.md and CONTRIBUTING*. Inspect the repository root, current branch, git status, staged diff, remotes, recent history, and remote refs. Do not print a remote URL that may contain credentials; reject URLs with embedded user information.
Verify GCM using the active platform reference. A successful version command means reuse the existing installation without installing or upgrading it. Configure GCM only when its helper is absent or conflicting.
The user creates a Gitea PAT with write:repository and enters the Gitea login plus PAT only in the local GCM prompt. The account must already have repository write access.
3. Choose the Repository Path
- Existing clone:
git fetch --prunefirst; do not merge automatically. - Existing remote without a clone: clone the target branch before copying prepared files.
- Empty remote: only after
git ls-remotesucceeds with no refs, initialize the confirmed default branch, normallymain, and add the clean HTTPS remote. - Dirty clone: preserve unrelated changes. If they overlap task paths or prevent a safe update, use a fresh clone or isolated worktree based on the latest remote branch.
Do not use force, reset, clean, stash, or destructive checkout as a shortcut.
4. Prepare and Validate the Commit
Set the user-confirmed Eapil identity only in the target repository:
git config --local user.name "<confirmed-name>"
git config --local user.email "<confirmed-id>@eapil.com"
Copy or edit only the intended paths. Stage with an explicit pathspec:
git add -- <path-1> <path-2>
git diff --cached --name-status
git diff --cached --stat
git diff --cached --check
git diff --cached
Confirm every staged path is in scope, deletions are intentional, no secret or transient file is present, and repository-required tests pass. If there is no staged change, report that the remote already contains the prepared content instead of creating an empty commit, unless the user explicitly requested an empty commit.
5. Commit, Push, and Verify
Commit with an intent-based message. Re-fetch before pushing when the remote may have advanced. Push normally to the target branch. If the default branch is protected, push a task branch and report that review or merge is required. Do not use --force, --force-with-lease, --no-verify, or TLS bypasses.
After a successful push, fetch the pushed branch and compare:
git rev-parse HEAD
git rev-parse "origin/<pushed-branch>"
git ls-remote origin "refs/heads/<pushed-branch>"
Report completion only when the local and remote SHAs match. Include the repository, branch, commit SHA and subject, exact changed paths, validation performed, and remaining user action.
Stop Conditions
Stop on ambiguous paths, missing Git identity, authentication or TLS failure, insufficient account/PAT permissions, unexpected staged files, validation failure, overlapping user changes, non-fast-forward history requiring judgment, protected-branch rejection, server-hook rejection, or a request to overwrite remote history.