| name | git-workflow |
| description | Essential Git patterns for effective version control, eliminating redundant Git guidance per agent. |
| user-invocable | false |
| version | 1.0.0 |
| category | agent-reference |
| effort | low |
Git Workflow
Essential Git patterns for effective version control. Eliminates ~120-150 lines of redundant Git guidance per agent.
Commit Best Practices
Conventional Commits Format
<type>(<scope>): <subject>
<body>
<footer>
Types:
feat: New featurefix: Bug fixdocs: Documentation onlyrefactor: Code change that neither fixes bug nor adds featureperf: Performance improvementtest: Adding or updating testschore: Build process, dependencies, tooling
Examples:
feat(auth): add OAuth2 authentication
Implements OAuth2 flow using Google provider.
Includes token refresh and validation.
Closes
fix(api): handle null response in user endpoint
Previously crashed when user not found.
Now returns 404 with error message.
perf(db): optimize user query with index
Reduces query time from 500ms to 50ms.
Atomic Commits
git commit -m "feat: add user authentication"
git commit -m "test: add auth tests"
git commit -m "docs: update API docs for auth"
git commit -m "add auth, fix bugs, update docs"
Branching Strategy
Git Flow (Feature Branches)
git checkout main
git pull origin main
git checkout -b feature/user-authentication
git add src/auth.py
git commit -m "feat(auth): implement login endpoint"
git checkout main
git pull origin main
git checkout feature/user-authentication
git rebase main
git push -u origin feature/user-authentication
Trunk-Based Development
git checkout main
git pull origin main
git checkout -b fix/null-pointer
git commit -m "fix: handle null in user query"
git push origin fix/null-pointer
Common Workflows
Updating Branch with Latest Changes
git checkout feature-branch
git fetch origin
git rebase origin/main
git add resolved_file.py
git rebase --continue
git checkout feature-branch
git merge origin/main
Undoing Changes
git reset --soft HEAD~1
git reset --hard HEAD~1
git checkout -- file.py
git revert abc123
git add forgotten_file.py
git commit --amend --no-edit
Getting a Temporary Clean Tree
When you need a clean tree to run one command — a baseline check, a bisect, a
build against origin/main — add a throwaway worktree instead of moving the
work already in your tree:
git worktree add .claude/worktrees/baseline-$$ origin/main
git worktree remove .claude/worktrees/baseline-$$
Your own tree keeps its changes throughout, so a command that dies partway
through leaves nothing to restore.
Under trusty-mpm orchestration this is the PM's pattern, not a dispatched
agent's: worktree removal is PM-executed via tm session prune-worktrees, and
tm hook --pm-guard denies an agent's git worktree remove (#5791). An agent
that needs a clean tree asks the PM for one.
Stashing Work
The stash stack is repo-global, not per-worktree: every worktree of a repo
shares one stack. Name each entry and restore it by ref, so you get back the
one you saved:
git stash push -u -m "WIP: authentication feature $(date +%s)"
git stash list
git stash apply 'stash@{0}'
Check that the restored files are the ones you saved before dropping the entry.
Cherry-Picking Commits
git cherry-pick abc123
git cherry-pick abc123 def456
git cherry-pick -n abc123
Resolving Conflicts
git status
<<<<<<< HEAD
Your changes
=======
Their changes
>>>>>>> branch-name
# 3. Mark as resolved
git add resolved_file.py
# 4. Continue operation
git rebase --continue # or git merge --continue
Viewing History
git log --oneline -10
git log --graph --oneline --all
git log --author="John Doe"
git log -- path/to/file.py
git show abc123
git diff main..feature-branch
Branch Management
git branch -a
git branch -d feature-branch
git branch -D feature-branch
git push origin --delete feature-branch
git branch -m old-name new-name
git checkout --track origin/feature-branch
Tags
git tag v1.0.0
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
git push origin --tags
git checkout v1.0.0
git tag -d v1.0.0
git push origin --delete v1.0.0
Advanced Operations
Interactive Rebase
git rebase -i HEAD~3
Bisect (Find Bug Introduction)
git bisect start
git bisect bad
git bisect good v1.0.0
git bisect bad
git bisect good
git bisect reset
Blame (Find Who Changed Line)
git blame file.py
git blame -w file.py
git blame -L 10,20 file.py
Git Hooks
npm run lint
npm test
npm run test:integration
Best Practices
✅ DO
- Commit frequently with atomic changes
- Write clear, descriptive commit messages
- Pull before push to avoid conflicts
- Review changes before committing (
git diff --staged)
- Use branches for features and fixes
- Keep commits small and focused
❌ DON'T
- Commit sensitive data (use
.gitignore)
- Commit generated files (build artifacts,
node_modules)
- Force push to shared branches (
git push --force)
- Commit work-in-progress to main
- Include multiple unrelated changes in one commit
- Rewrite public history
.gitignore Patterns
# Dependencies
node_modules/
venv/
__pycache__/
# Build outputs
dist/
build/
*.pyc
*.o
*.exe
# IDE
.vscode/
.idea/
*.swp
# Secrets
.env
*.key
*.pem
secrets.yml
# OS
.DS_Store
Thumbs.db
# Logs
*.log
logs/
Quick Command Reference
git status
git diff
git diff --staged
git add .
git commit -m "message"
git push
git branch
git checkout -b branch-name
git merge branch-name
git pull
git fetch
git reset HEAD~1
git checkout -- file
git revert commit-hash
git log
git log --oneline
git show commit-hash
Remember
- Commit often - Small commits are easier to review and revert
- Descriptive messages - Future you will thank present you
- Pull before push - Stay synchronized with team
- Use branches - Keep main stable
- Review before commit - Check what is being committed
