Skip to content

02-git-workflow.md

Latest commit

 

History

History
115 lines (81 loc) · 2.71 KB

02-git-workflow.md

File metadata and controls

115 lines (81 loc) · 2.71 KB

Git Workflow

This is the default Git workflow for agent-driven repositories.

Branching Model

  • main is the protected trunk.
  • All meaningful work happens on short-lived branches.
  • Default merge strategy is squash merge unless the repo explicitly preserves multi-commit history.
  • Agents do not work directly on main.

Start New Work

Always start from the remote default branch, not a possibly stale local branch.

Single active PR

git fetch origin
git switch --detach origin/main
git switch -c <branch-name>

Multiple active PRs

git fetch origin
git worktree add .worktrees/<slug> origin/main
cd .worktrees/<slug>
git switch -c <branch-name>

Use git worktree when parallel PRs must exist at the same time. Do not stack unrelated local branches in one checkout.

Commit Policy

git add <files>
git commit -m "<type>(<scope>): <summary>"

Rules:

  • commit only in-scope files
  • keep commits reviewable
  • do not bundle unrelated workspace dirt
  • each commit should leave the branch in a coherent state

Keep the Branch Current

git fetch origin
git rebase origin/main

If the branch was already pushed:

git push --force-with-lease

Use --force-with-lease, never --force.

Branch Proof Before Review

Before claiming a branch is PR-ready:

git fetch origin
git rev-parse HEAD
git rev-parse origin/main
git log --oneline origin/main..HEAD
git diff --stat origin/main..HEAD
git status --short

The diff against origin/main should contain only the scoped work.

Conflict Resolution

  1. git fetch origin
  2. git rebase origin/main
  3. resolve conflicts deliberately
  4. rerun validation
  5. git push --force-with-lease if needed

Do not blindly accept ours or theirs without understanding the behavior change.

Protected Branch Rules

main should require:

  • pull requests before merge
  • required status checks
  • resolved review conversations
  • at least one approval

If the repository volume justifies it, add merge queue on top of branch protection.

Force-Push Policy

Situation Allowed? Default
private local cleanup before PR exists Yes allowed
branch rebased before review starts Yes allowed with --force-with-lease
active review in progress Avoid prefer follow-up commits unless the repo requests a history rewrite
main No forbidden

Recovery Operations

Use the least destructive tool that solves the problem.

  • git revert <commit> for undoing merged history
  • git cherry-pick <commit> for transplanting a known-good change
  • git stash -u for short-lived local context switches

Avoid destructive commands like git reset --hard unless the repo owner explicitly approves it.