git-workflow
GitHub提供Git协作最佳实践，涵盖分支策略（Trunk-Based/GitFlow）、提交规范（Conventional Commits）及代码审查文化。包含成熟度模型与实操指南，旨在提升版本控制质量与团队协作效率。
Trigger Scenarios
Install
npx skills add cosmicstack-labs/mercury-agent-skills --skill git-workflow -g -y
SKILL.md
Frontmatter
{
"name": "git-workflow",
"metadata": {
"tags": [
"git",
"version-control",
"branching",
"code-review",
"collaboration"
],
"author": "cosmicstack-labs",
"version": "1.0.0",
"category": "development"
},
"description": "Git best practices, branching strategies, commit conventions, and code review patterns"
}
Git Workflow
Master the fundamentals of version control collaboration — from branching strategy to commit hygiene to review culture.
Core Principles
1. Commits Are Communication
Every commit message is a message to your future self and your teammates. Write for the reader who needs to understand why a change was made, not just what changed.
2. Branch Intentionally
Your branching strategy should match your team size, release cadence, and deployment model. The best strategy is the one your team actually follows consistently.
3. Review With Empathy
Code review is a conversation, not an inspection. The goal is shared understanding and improved quality, not catching mistakes.
4. Rebase Thoughtfully
History matters. Clean history helps debugging and release management. But never rebase shared branches without team coordination.
Git Workflow Maturity Model
| Level | Branching | Commits | Reviews | CI |
|---|---|---|---|---|
| 1: Ad-hoc | All on main | "Update" messages | None | None |
| 2: Basic | Feature branches | Some context in messages | Occasional | Lint checks |
| 3: Standard | Trunk-based or GitFlow | Conventional commits | Required PRs | Full test suite |
| 4: Advanced | Short-lived branches | Atomic, rebased commits | Automated + manual | Deploy previews |
| 5: Elite | Feature flags on trunk | Semantic versioning from commits | Async + sync pairing | Auto-deploy to prod |
Target: Level 3+ for team projects. Level 4+ for high-velocity teams.
Actionable Guidance
Branching Strategies
Trunk-Based Development (Recommended for most teams)
- Main branch: Always deployable. Protected — no direct pushes.
- Feature branches: Short-lived (1-2 days max). Branch from main, merge back to main.
- Release branches: Cut from main at release time. Bug fixes cherry-picked.
main: o---o---o---o---o---o---o
\ /
feature-A: o---o---o
\
feature-B: o---o
When to use: Continuous deployment, small teams, mature CI.
GitFlow (For scheduled releases)
- main: Production releases only
- develop: Integration branch
- feature/*: Branch from develop, merge to develop
- release/*: Branch from develop, merge to main + develop
- hotfix/*: Branch from main, merge to main + develop
When to use: Scheduled releases, multiple versions in support, larger teams.
Commit Conventions
Conventional Commits (Recommended)
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
Types: feat, fix, docs, style, refactor, perf, test, chore, ci
feat(auth): add OAuth2 login flow
Implements Google and GitHub OAuth providers.
Closes #142
BREAKING CHANGE: Drops support for password-based auth
Benefits: Automatic changelog generation, semantic versioning, clear intent.
Atomic commits: Each commit should represent one logical change. If you find yourself writing "and" in the description, split the commit.
# Bad: Mixed concerns
"Add user settings page and fix login bug and update deps"
# Good: Three atomic commits
"feat(settings): add user preferences page"
"fix(auth): handle expired session tokens"
"chore(deps): update lodash to 4.17.21"
Code Review Patterns
Review Checklist
For every PR:
- Does the code solve the stated problem?
- Are there tests for new functionality?
- Do existing tests still pass?
- Is the code at the right abstraction level?
- Are error paths handled?
- Are there security concerns (XSS, injection, auth)?
- Is documentation updated?
Giving Feedback
Bad: "This is wrong. Do it like this instead."
Good: "I'm concerned about edge cases here — what happens if the user list is empty? Consider using .get() with a default."
Bad: "This function is too long."
Good: "The validation logic and the rendering logic seem like separate concerns. Could we extract the validation into its own function?"
Review types:
- Nitpick: Minor style preference, non-blocking. Prefix with "nit:"
- Suggestion: Alternative approach, discuss. "What do you think about..."
- Blocking: Must be resolved before merge. Explain why it's critical.
- Question: Seeking understanding. "I'm trying to understand why..."
Responding to Reviews
- Don't take feedback personally. Code reviews are about the code, not you.
- Thank reviewers for catching issues.
- If you disagree, explain your reasoning — but be open to being wrong.
- When you make a requested change, resolve the conversation.
- If something is deliberately chosen, explain (and document) the tradeoff.
Git Hygiene
Before You Commit
# Stage related changes only
git add -p # Interactive staging — commit only what's relevant
# Review your diff before committing
git diff --staged
# Write the commit message first, then commit
git commit # Opens editor — write a good message
Before You Push
# Rebase on latest main
git fetch origin
git rebase origin/main
# Check what you're about to push
git log origin/main..HEAD
# Squash fixup commits
git rebase -i origin/main
Pull Request Best Practices
- Keep PRs small: <400 lines ideal. Large PRs get shallow reviews.
- One concern per PR: Don't refactor 10 files and add a feature in the same PR.
- Write a good description: What, why, how, testing, screenshots.
- Self-review first: Go through your own diff before requesting review.
- Respond promptly: Don't let PRs languish for days.
Common Mistakes
- Committing secrets: Never commit API keys, passwords, or tokens. Use
.envfiles and secret managers. - Large untracked files: Check your
.gitignore. Don't commitnode_modules, build artifacts, or generated files. - Merge commits in a clean-history workflow: If your team prefers linear history, rebase instead of merging.
- Forcing pushes to shared branches:
git push --forceis dangerous on shared branches. Use--force-with-lease. - Reviewing too late: Review within 24 hours. Stale PRs create context-switching overhead.
- Merging failing CI: Never merge a PR with failing checks, even if "it works on my machine."
- Descriptions are useless: "Fix bug" tells no one anything. "Fix timeout in user search when database has >10k records" tells everything.
Version History
- 38e2523 Current 2026-07-05 19:38
