git-workflow

name	git-workflow
description	Consistent git practices, recovery patterns, and safe operations.
lastReviewed	2026-04-30T00:00:00.000Z

Git Workflow Skill

Consistent git practices, recovery patterns, and safe operations.

⚠️ Staleness Warning

Git core is stable, but GitHub features (Actions, CLI, Copilot integration) evolve.

Refresh triggers:

• GitHub CLI major updates
• GitHub Actions runner changes
• New git features (e.g., git switch, git restore)
• GitHub Copilot CLI integration

Last validated: February 2026 (Git 2.45+, GitHub CLI 2.x)

Check current state: Git Release Notes, GitHub CLI

---

Decision Table

Scenario	Command	Notes
Undo last commit, keep changes	git reset --soft HEAD~1	Safe, preserves work
Restore single file	git checkout HEAD -- path/to/file	Discards file changes
Restore entire folder	git checkout HEAD -- .github/	Discards folder changes
Before risky operation	git add -A; git commit -m "checkpoint"	Always checkpoint first
Discard all uncommitted	git reset --hard HEAD	Destructive, no recovery
Reset to remote state	git reset --hard origin/main	Destructive, syncs to remote
Save work temporarily	git stash → git stash pop	For quick context switch
Isolated experimental work	git worktree add ../feature branch	Agent-friendly isolation

---

Commit Message Convention

type(scope): brief description

- Detail 1
- Detail 2

Types: feat, fix, refactor, docs, chore, test, style

Examples:

feat(skills): add git-workflow skill
fix(sync): resolve race condition in background sync
refactor(skills): migrate domain-knowledge to skills architecture
docs(readme): update installation instructions
chore(deps): bump typescript to 5.3

Before Risky Operations

# ALWAYS commit before risky operations
git add -A; git commit -m "checkpoint: before [risky thing]"

# For extra safety, tag it
git tag "safe-point-$(date +%Y-%m-%d-%H%M)"

Recovery Patterns

Undo Last Commit (keep changes)

git reset --soft HEAD~1

Restore Single File

git checkout HEAD -- path/to/file

Restore Folder

git checkout HEAD -- .github/

Hard Reset to Known Good State

git reset --hard HEAD           # Discard all uncommitted changes
git reset --hard origin/main    # Reset to remote state
git reset --hard <tag-name>     # Reset to tagged state

Find Last Good Commit

git log --oneline -20           # Recent history
git log --oneline .github/ -10  # History for specific folder

Branching Strategy

main
 └── feature/short-description
 └── fix/issue-number
 └── release/v3.7.0

Rules:

• main is always deployable
• Feature branches for experimental work
• Merge via PR when possible, direct commit for small fixes
• Delete branches after merge

Conflict Resolution

1. Pull before push: git pull --rebase origin main
2. If conflicts: Resolve in editor, then git add . + git rebase --continue
3. If stuck: git rebase --abort to start over

Stashing

git stash                       # Save work-in-progress
git stash pop                   # Restore and delete stash
git stash list                  # See all stashes
git stash drop                  # Delete top stash

Worktrees (Agent Isolation)

VS Code background agents use git worktree to isolate changes. Understanding worktrees is useful when debugging agent sessions.

# Create a worktree for isolated work
git worktree add ../project-feature feature-branch

# List all worktrees
git worktree list

# Remove a worktree (prune stale links)
git worktree remove ../project-feature
git worktree prune

VS Code integration (1.109+):

• git.worktreeIncludeFiles — copy gitignored files (e.g., .env) into agent worktrees
• Background agents auto-commit at end of each turn within their worktree
• Check Agent Sessions view to see which worktree an agent is using

Anti-Patterns

• ❌ git push --force on shared branches
• ❌ Committing secrets or credentials
• ❌ Giant commits with unrelated changes
• ❌ Vague messages like "fix stuff" or "update"