git-workflow

name	git-workflow
description	Git workflow assistant for branching, commits, PRs, and conflict resolution. Use when user asks about git strategy, branch management, or PR workflow.

Git Workflow

Help with Git operations and workflow best practices.

Core Principles

1. Commit early and often

Make small, frequent commits rather than accumulating large batches of changes.

• Commit after every logical unit of work — even if it's just "wip: explore approach" or "wip: add failing test"
• A commit is cheap; losing work is expensive
• Small commits make reviews easier, bisection faster, and rollbacks safer
• Don't wait until everything is "perfect" — a messy commit history can be cleaned later with interactive rebase
• Prefer git commit -m "wip: <description>" over leaving work uncommitted for long stretches

2. Use git stash instead of discarding

When you need to clear or reset uncommitted work, never just delete it — stash it with an explanation.

• Use git stash push -m "<reason>: <description>" to preserve work and record why it was stashed
• The stash remains in Git history and can be recovered via git stash list or git reflog
• This protects against mistakes, dead ends that turn out to be useful later, or context lost during interruptions
• If you later decide the stashed work is truly worthless — only then drop it explicitly with git stash drop <stash>
• Explaining the stash in the message also helps future-you (or the next agent) understand what was happening

Example:

# Bad: work is just gone
rm -rf changed-files/
git checkout -- .

# Good: work is preserved with context
git stash push -m "pivot: abandoning approach A for approach B after benchmark regression"
git stash push -m "interrupted: switching to urgent bugfix PR #123"

3. Use worktrees for new work

Start new work in a fresh worktree rather than working directly on main or the current branch.

• Create a worktree for every distinct task or feature: git worktree add -b feat/description ../worktrees/feat-description
• Keeps main clean and available for quick reference, hotfixes, or parallel reviews
• Eliminates risk of accidentally committing work-in-progress to the trunk
• Makes it safe to run tests, builds, and linting in isolation without polluting the main checkout
• When done, remove the worktree: git worktree remove <path> — the branch remains for PR/merge
• If the project has a worktree management extension or script, prefer that over raw git worktree commands

4. Clean up history before sharing

Never merge or push to origin while wip: commits remain in the stack, unless the user explicitly says otherwise.

• WIP commits are for local iteration only — they are checkpoints, not publication-ready units
• Before pushing or opening a PR, restructure history so every commit is a logical, self-contained unit of work
• Each commit should tell a clear story: what changed, why it changed, and ideally be independently buildable/testable
• Squash related wip: commits using interactive rebase: git rebase -i main
• Rename wip: commits to proper Conventional Commit messages that describe the final intent
• If a commit cannot stand on its own (e.g. "wip: broken test"), squash it into the commit that makes it pass
• Only ever push wip: commits to origin if the user explicitly requests it (e.g. "just push what I have")

Example — cleaning up before a PR:

# Check what's in the stack
git log --oneline main..HEAD

# If there are wip: commits, restructure
git rebase -i main
#   pick    feat(widget): add new rendering pipeline
#   squash  wip: failing test for edge case
#   squash  wip: fix off-by-one in renderer
#   pick    perf(widget): cache computed layout
#   drop    wip: try alternative approach (abandoned)

# Push the cleaned branch
git push origin feat/widget-rendering

See also Core Principle #1: Commit early and often — commit freely with wip: during development, but clean up before sharing.

Capabilities

Branch Strategy

# Check current state
git branch -a
git log --oneline -20
git status

Recommend branching strategy based on project:

• Solo: main + feature branches
• Team: main + develop + feature/fix branches
• Release: GitFlow (main/develop/release/hotfix)

Worktree-aware workflow

When the repository uses git worktrees, do not assume the current checkout is the main repo root. First establish:

git rev-parse --show-toplevel
git rev-parse --git-common-dir
git worktree list --porcelain

Prefer worktrees for all new work. See Core Principle #3: Use worktrees for new work.

If the oh-pi worktree extension is available, prefer:

• /worktree status or git rev-parse --show-toplevel — show the current worktree and repo root
• /worktree list or git worktree list --porcelain — show all repo worktrees

For pi-owned worktrees:

• always record a human-readable purpose when creating one
• preserve owner/session metadata if the tool supports it so cleanup decisions stay explainable
• only clean up worktrees you own by default
• do not clean external/manual worktrees unless the user explicitly asks

When finishing work in a worktree:

1. Push the branch: git push origin <branch>
2. Open a PR from the worktree branch
3. Remove the worktree after merge: git worktree remove <path>

Commit Messages

Follow Conventional Commits

Small commits are better than perfect commits. See Core Principle #1: Commit early and often.

Use these prefixes:

feat(scope): add new feature
fix(scope): fix bug description
refactor(scope): restructure code
docs(scope): update documentation
test(scope): add/update tests
chore(scope): maintenance tasks

For work-in-progress commits (which are encouraged!), use wip: prefix or chore(wip)::

git commit -am "wip: explore trie-based approach for tokenization"
git commit -am "wip: failing test for edge case in parser"
git commit -am "wip: checkpoint before attempting refactor"

Clean up before opening a PR:

git rebase -i main  # squash related wip commits

But never leave work uncommitted for long — stash or commit, don't let it sit dirty.

PR Workflow

1. git diff main --stat — Review changes
2. Generate PR title and description
3. Suggest reviewers based on changed files (git log --format='%an' -- <files>)

PR link in summaries

When a PR has been opened, always include the full GitHub PR URL in any summary or status update you provide. This makes it easy for the user to click through to the PR directly.

Example summary format:

PR: https://github.com/owner/repo/pull/42

Use gh pr view --json url --jq .url to retrieve the URL if you do not already have it.

Non-interactive safety for agent-run Git/GitHub commands

When the agent runs git or gh, avoid opening an interactive editor or prompt.

A lot of Git entrypoints use different editor config keys, so avoid surprises by disabling both:

• core.editor / GIT_EDITOR (commit, merge, tag message editing)
• sequence.editor / GIT_SEQUENCE_EDITOR (interactive rebase todo-list editing)

Use this pattern for non-interactive flows:

GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true git -c core.editor=true -c sequence.editor=true rebase --continue

• For commits, always pass the message on the command line:

  git commit -m "fix(scope): message"
  

• For merges that should reuse the existing message, use:

  git merge --no-edit
  

• For any other git command that could open an editor, set GIT_EDITOR=true and GIT_SEQUENCE_EDITOR=true (plus -c core.editor=true -c sequence.editor=true) for that invocation.
• For GitHub CLI commands, disable terminal prompts and provide all required fields explicitly:

  GH_PROMPT_DISABLED=1 gh pr create --title "..." --body "..."
  GH_PROMPT_DISABLED=1 gh pr merge --squash --delete-branch
  

• Only allow interactive editors/prompts when the user explicitly asks the agent to leave them enabled.

Conflict Resolution

1. git diff --name-only --diff-filter=U — Find conflicted files
2. Read each conflicted file
3. Understand both sides of the conflict
4. Resolve with minimal changes preserving intent from both sides

Interactive Rebase

Guide through git rebase -i for cleaning up history before PR.

If the agent is resolving conflicts during a rebase, continue with a non-interactive command such as:

GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true git -c core.editor=true -c sequence.editor=true rebase --continue