| name | git-workflow |
| description | Git operations, commits, branches, remotes, GitHub/GitLab/Forgejo repository setup, merge, rebase, reset, or history rewrite. Not for SSH client/server troubleshooting; use ssh. Not for Forgejo Actions; use forgejo-actions. |
Git Workflow Guidelines
Compact index for Git operations and repository hosting. Load linked files for worktrees or provider-specific setup.
Boundary
| Need | Use |
|---|
| Git state, history, branches, worktrees, remotes, or repository hosting | git-workflow |
| SSH transport, authentication, keys, agents, host verification, or sshd | ssh |
| Forgejo Actions workflows and runners | forgejo-actions |
Project-specific rules
- Default branch is
main.
- Never force-push submodule repos.
- Do not amend or rebase already-pushed submodule commits.
- Pull inside a submodule before updating the parent repo's pinned submodule reference.
- If submodule fetch fails:
git pull --no-recurse-submodules then git submodule update --init --recursive.
- Git identity is directory/remote driven; machine-specific SSH config belongs in gitignored local files.
- For Pi structured commits, run
commit_plan before commit_stage/commit_create so their tokens bind mutation to the exact planned state. Local commits do not require separate permission; keep them coherent and in scope. Push only when the user explicitly asks.
Practical steps
- Inspect state before mutation:
git status --short --branch and relevant diffs.
- For worktree status questions, run live state first:
git worktree list --porcelain and git status --short --branch; report actual worktrees, branches, dirty state, stale/prunable entries, and convention mismatches.
- Before branch or worktree changes, verify the current worktree is clean or get explicit direction to preserve work.
- Separate user changes from agent changes; never stage unrelated files.
- Run repository-required secret and whitespace checks before committing.
- Use
wip: ... save-point commits when preserving work before switching or syncing; treat them as local and temporary unless the user explicitly asks to push.
- Prefer revert/restore over destructive history operations; ask before resets, force pushes, or deleting stale worktree directories.
Quick validation
| Purpose | Commands |
|---|
| Status | git status --short --branch |
| Worktree status | git worktree list --porcelain plus git status --short --branch in the relevant worktree |
| Review unstaged diff | git diff -- <path> |
| Review staged diff | git diff --cached -- <path> |
| Whitespace check | git diff --check / git diff --cached --check |
| Submodule state | git submodule status --recursive |
Anti-patterns
- Staging with broad
git add . in a dirty worktree.
- Amending, rebasing, resetting, or force-pushing without explicit approval and remote-state awareness.
- Editing
.gitignore to hide generated artifacts without understanding why they appeared.
- Mixing formatting-only churn with behavior changes in the same commit.
Optional references
