git-workflows（git 工作流程）

Git & GitHub Workflows (via Grove Wrap)

All git and GitHub operations go through gw — never use raw git or gh commands directly. Grove Wrap adds safety tiers, Conventional Commits enforcement, protected branch guards, and agent-safe defaults.

When to Activate

Activate this skill when:

• Making git commits, pushing, pulling, branching, or stashing
• Creating, reviewing, or merging pull requests
• Creating, viewing, or closing GitHub issues
• Checking CI/workflow run status
• Reviewing git history, diffs, or blame
• Resolving merge conflicts
• Any version control operation

Safety System

gw enforces a three-tier safety model:

Protected branches (main, master, production, staging) can NEVER be force-pushed, even with --force.

Agent mode (auto-detected for Claude Code): stricter row limits, force operations blocked, all operations audit-logged.

Dry run any command with --dry-run to preview what would happen.

Conventional Commits Format

gw validates commit messages against Conventional Commits automatically. Format:

<type>(<optional scope>): <brief description>

<optional body>

<optional footer>

Commit Types

Breaking changes: Add an exclamation mark after the type, e.g. feat!: replace XML config with YAML

Git Commands — Reading (Always Safe)

gw git status                  # Enhanced git status
gw git log                     # Formatted commit history
gw git log --limit 20          # Last 20 commits
gw git diff                    # Show changes
gw git diff --staged           # Show staged changes
gw git blame file.ts           # Blame with context
gw git show abc123             # Show commit details

Git Commands — Writing (Needs --write)

gw git add --write .                              # Stage files
gw git add --write src/lib/thing.ts               # Stage specific file
gw git commit --write -m "feat: add new feature"  # Commit (validates conventional commits!)
gw git push --write                               # Push to remote
gw git pull --write                               # Pull from remote
gw git pull --write --rebase                      # Pull with rebase strategy
gw git branch --write feature/new-thing           # Create branch
gw git switch --write feature/new-thing           # Switch branches
gw git stash --write                              # Stash changes
gw git stash --write pop                          # Pop stash
gw git unstage --write file.ts                    # Unstage files

Git Commands — Dangerous (Needs --write --force)

gw git push --write --force          # Force push (blocked to protected branches!)
gw git reset --write --force HEAD~1  # Hard reset
gw git rebase --write --force main   # Rebase onto main
gw git merge --write --force feature # Merge branches

Grove Shortcuts

These combine common multi-step operations into single commands:

# Quick save: stage all + WIP commit
gw git save --write

# Quick sync: fetch + rebase + push
gw git sync --write

# WIP commit that skips hooks
gw git wip --write

# Undo last commit (keeps changes staged)
gw git undo --write

# Amend last commit message
gw git amend --write -m "better message"

# FAST MODE: skip ALL hooks, commit + push in one shot
gw git fast --write -m "fix: emergency hotfix"

Branching Strategy

Branch Naming

feature/feature-name    # New features
fix/bug-description     # Bug fixes
experiment/new-idea     # Experiments
release/v1.0.0          # Releases

Feature Branch Workflow

# Create and switch to feature branch
gw git branch --write feature/user-auth
gw git switch --write feature/user-auth

# Work and commit
gw git add --write .
gw git commit --write -m "feat: add JWT authentication"

# Push and create PR
gw git push --write
gw gh pr create --write --title "feat: add JWT authentication"

GitHub — Pull Requests

# Reading (always safe)
gw gh pr list                   # List open PRs
gw gh pr view 123               # View PR details
gw gh pr status                 # PR status (CI, reviews, etc.)

# Writing (needs --write)
gw gh pr create --write --title "feat: new thing" --body "Description"
gw gh pr comment --write 123 "LGTM!"
gw gh pr merge --write 123      # Merge PR (prompts for confirmation)

GitHub — Issues

# Reading (always safe)
gw gh issue list                # List open issues
gw gh issue view 456            # View issue details

# Writing (needs --write)
gw gh issue create --write --title "Bug: thing broke"
gw gh issue close --write 456

GitHub — Workflow Runs (CI)

# Reading (always safe)
gw gh run list                  # List recent runs
gw gh run view 12345678         # View run details
gw gh run watch 12345678        # Watch a running workflow

# Writing (needs --write)
gw gh run rerun --write 12345678 --failed  # Rerun failed jobs
gw gh run cancel --write 12345678          # Cancel a run

GitHub — API & Rate Limits

# GET requests (always safe)
gw gh api repos/AutumnsGrove/Lattice

# POST/PATCH (needs --write)
gw gh api --write repos/{owner}/{repo}/labels -X POST -f name="bug"

# DELETE (needs --write --force)
gw gh api --write --force repos/{owner}/{repo}/labels/old -X DELETE

# Check rate limit status
gw gh rate-limit

GitHub — Project Boards

gw gh project list              # List project boards
gw gh project view              # View current project

Commit Examples

Feature

gw git commit --write -m "feat: add dark mode toggle

- Implement theme switching logic
- Add localStorage persistence
- Update CSS variables"

Bug Fix with Issue Link

gw git commit --write -m "fix: correct timezone handling bug

Fixes off-by-one error in date calculations.

Closes #123"

Breaking Change

gw git commit --write -m "feat!: replace XML config with YAML

BREAKING CHANGE: XML configuration no longer supported.
See docs/migration.md for upgrade instructions."

Agent-Optimized Commands (NEW)

These commands are specifically designed for agentic workflows:

Session Start (Always run this first!)

gw context                      # One-shot session snapshot (rich output)
gw --json context               # JSON snapshot (branch, changes, packages, issues)

Ship with Auto-Stage

# Stage all + format + check + commit + push in ONE command
gw git ship --write -a -m "feat: implement feature"

# Equivalent to: gw git add --write . && gw git ship --write -m "..."

PR Preparation

gw git pr-prep                  # Full PR readiness report
gw --json git pr-prep           # JSON: commits, files, packages, suggested title

Targeted CI

gw ci --affected               # Only check packages with changes
gw ci --affected --fail-fast   # Fast feedback: stop on first failure
gw ci --diagnose               # Structured error output when steps fail
gw --json ci --affected        # JSON with parsed error details

Batch Issue Creation

# Create multiple issues from JSON
gw gh issue batch --write --from-json issues.json
echo '[{"title":"Bug: thing","labels":["bug"]}]' | gw gh issue batch --write --from-json -

Impact Analysis (via gf)

gf impact src/lib/auth.ts       # Who imports this? What tests? Which routes?
gf test-for src/lib/auth.ts     # Find tests covering this file
gf diff-summary                 # Structured diff with per-file stats
gf --json impact src/lib/auth.ts  # All of the above as parseable JSON

Common Workflows

Start a new feature

gw context                      # Orient: what branch, what's changed?
gw git branch --write feature/my-feature
gw git switch --write feature/my-feature
# ... make changes ...
gw git ship --write -a -m "feat: implement my feature"
gw git pr-prep                  # Check readiness
gw gh pr create --write --title "feat: implement my feature"

Quick fix and ship

gw git fast --write -m "fix: correct typo in header"

Ship with full checks

gw git ship --write -a -m "feat: add auth refresh"
# This does: auto-stage all → format → type-check → commit → push

Check CI before merging

gw ci --affected --fail-fast    # Quick: only changed packages
gw gh pr status                 # See CI status on current PR
gw gh run list                  # See recent workflow runs
gw gh run watch 12345678        # Watch the current run

Pull latest changes

gw git pull --write             # Pull from remote (merge strategy)
gw git pull --write --rebase    # Pull with rebase (cleaner history)
gw git pull --write origin main # Pull specific remote/branch

Sync branch with main

gw git sync --write             # Fetch + rebase + push

Save work in progress

gw git save --write             # Stage all + WIP commit
# or
gw git stash --write            # Stash without committing

Merge Conflicts

When conflicts occur during sync/rebase/merge:

gw git status                   # See conflicted files

# Edit files to resolve conflicts:
# <<<<<<< HEAD
# Your changes
# =======
# Incoming changes
# >>>>>>> feature-branch

# After resolving:
gw git add --write resolved-file.ts
gw git commit --write -m "fix: resolve merge conflicts"

Worktrees

Work on multiple branches simultaneously without stashing:

gw git worktree add --write ../grove-hotfix fix/urgent
gw git worktree list
gw git worktree remove --write ../grove-hotfix

Best Practices

DO

• Start every session with gw context (or gw --json context for structured data)
• Use gw for all git/GitHub operations (never raw git or gh)
• Use gf for all codebase search (never raw grep or rg)
• Use Conventional Commits format (gw enforces this)
• Use gw git ship --write -a -m "..." for the fastest commit+push workflow
• Use gw ci --affected instead of full CI when possible
• Use gw git pr-prep before creating PRs
• Use gf impact before making changes to understand blast radius
• One logical change per commit
• Keep subject under 50 characters
• Use imperative mood ("Add" not "Added")
• Use --dry-run to preview destructive operations

DON'T

• Use raw git or gh commands directly
• Force-push to protected branches
• Use vague messages ("Update files", "Fix stuff")
• Combine multiple unrelated changes in one commit
• Skip the --write flag (even if it seems tedious — it's a safety net)

Troubleshooting

"Protected branch"

You tried to force-push to main. Create a PR instead:

gw gh pr create --write --title "My changes"

"Rate limit exhausted"

gw gh rate-limit               # Check when it resets

Committed to wrong branch

gw git log --limit 1            # Note the commit hash
gw git switch --write correct-branch
# Cherry-pick the commit, then remove from wrong branch

Need to undo last commit

gw git undo --write             # Keeps changes staged

Related Resources

• gw source: tools/grove-wrap-go/ — Go source code and Makefile
• gw spec: docs/specs/gw-cli-spec.md — Technical specification
• Git guide: AgentUsage/git_guide.md — Extended documentation
• MCP integration: gw mcp serve exposes all commands as MCP tools for Claude Code