Git workflow
Skill krzysztofsurdy/code-virtuoso/skills/knowledge/git-workflow
Git workflow patterns and version control best practices for teams of any size. Use when the user asks to choose a branching strategy (trunk-based, GitHub Flow, Git Flow, GitLab Flow), define commit conventions, set up PR workflows, plan release management, structure a monorepo, or establish team git standards. Covers branch naming, merge vs rebase, conventional commits, semantic versioning, changelog generation, and protected branch policies.From its SKILL.md
npx -y skills add krzysztofsurdy/code-virtuoso --skill git-workflowAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 20 stars20 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.6 KB, ~2.1k tokens by cl100k_base, as published. Nobody here has run it
Git Workflow
Effective version control is not just about tracking changes - it is about enabling teams to collaborate predictably, release confidently, and maintain a history that tells a coherent story. The right workflow depends on team size, release cadence, and how much process the project can absorb without slowing down.
Choosing a Branching Strategy
No single branching model fits every team. The right choice depends on how often you release, how large your team is, and how much ceremony you can tolerate.
Strategy Comparison
| Strategy | Release Cadence | Team Size | Complexity | Best For |
|---|---|---|---|---|
| Trunk-Based | Continuous (multiple per day) | Any (works best with strong CI) | Low | SaaS, cloud-native, teams with mature CI/CD |
| GitHub Flow | On-demand (per merged PR) | Small to medium | Low | Web apps, startups, teams wanting simplicity |
| Git Flow | Scheduled / versioned releases | Medium to large | High | Packaged software, mobile apps, multiple supported versions |
| GitLab Flow | Environment-promoted | Medium to large | Medium | Teams needing environment-specific branches (staging, production) |
Decision Guide
- Do you deploy continuously? - Use trunk-based development. Short-lived branches (hours, not days), feature flags for incomplete work, and strong CI are prerequisites.
- Do you deploy on merge but want review gates? - Use GitHub Flow. One long-lived branch (main), feature branches, pull requests as the merge gate.
- Do you ship versioned releases on a schedule? - Use Git Flow. Separate develop and main branches, release branches for stabilization, hotfix branches for emergency patches.
- Do you promote through environments? - Use GitLab Flow. Environment branches (staging, production) sit downstream of main, and merges flow in one direction.
See Branching Strategies Reference for detailed mechanics, feature flag integration, and migration paths between strategies.
Commit Message Conventions
Good commit messages serve three audiences: reviewers reading the PR, developers reading git log next month, and automation tools generating changelogs and version bumps.
The Conventional Commits Format
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
Common Commit Types
| Type | Purpose | Version Impact |
|---|---|---|
feat | New feature visible to users | Minor bump |
fix | Bug fix | Patch bump |
refactor | Code restructuring with no behavior change | None |
perf | Performance improvement | Patch bump |
test | Adding or updating tests | None |
docs | Documentation only | None |
chore | Tooling, dependencies, build config | None |
ci | CI/CD pipeline changes | None |
build | Build system or dependency changes | None |
Breaking Changes
Append ! after the type or add a BREAKING CHANGE: footer to signal incompatible changes. Either notation triggers a major version bump when used with automated release tooling.
feat(api)!: remove deprecated /v1/users endpoint
BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.
Semantic Versioning Alignment
| Commit Contains | Version Bump | Example |
|---|---|---|
fix: | Patch (1.0.0 -> 1.0.1) | Bug corrections |
feat: | Minor (1.0.0 -> 1.1.0) | New capabilities |
BREAKING CHANGE or ! | Major (1.0.0 -> 2.0.0) | Incompatible changes |
See Commit Conventions Reference for scope naming patterns, multi-line body guidelines, changelog automation setup, and git hook validation.
Pull Request Workflow
Pull requests are the primary collaboration point in most git workflows. Their quality directly affects review speed, defect discovery, and team velocity.
PR Size Guidelines
| PR Size (lines changed) | Review Quality | Recommended |
|---|---|---|
| < 50 | Excellent - reviewer catches most issues | Ideal for stacked PRs |
| 50-200 | Good - manageable cognitive load | Sweet spot for most changes |
| 200-400 | Acceptable - requires focused review time | Upper bound for single reviews |
| 400+ | Poor - reviewer fatigue, defects slip through | Split into smaller PRs |
Core PR Practices
- One concern per PR - A PR should do one thing: add a feature, fix a bug, refactor a module. Mixing concerns makes review harder and reverts riskier.
- Write a clear description - State what changed, why it changed, and how to verify it. Link to the relevant ticket or issue.
- Keep the diff reviewable - Move large mechanical changes (renames, formatting) into separate PRs from logic changes.
- Respond to feedback promptly - Stale PRs accumulate merge conflicts and block dependent work.
Merge Strategies
| Strategy | History Shape | Best For |
|---|---|---|
| Merge commit | Preserves branch topology, creates merge node | Open-source projects, audit trails |
| Squash and merge | Collapses branch into single commit on main | Feature branches with messy intermediate commits |
| Rebase and merge | Linear history, no merge commits | Teams wanting clean, linear logs |
See PR Patterns Reference for description templates, CODEOWNERS configuration, branch protection rules, stacked PR workflows, and review assignment strategies.
Release Management
Release management bridges development and deployment. The approach depends on whether releases are continuous, scheduled, or versioned.
Release Models
| Model | How It Works | When to Use |
|---|---|---|
| Continuous release | Every merged PR deploys automatically | SaaS with strong CI/CD and monitoring |
| Scheduled release | Changes accumulate, release on a cadence (weekly, biweekly) | Teams needing coordination windows |
| Versioned release | Explicit version tags, release branches for stabilization | Libraries, APIs, packaged software |
Git Tags for Releases
Tags mark specific commits as release points. Use annotated tags for releases because they store author, date, and message metadata.
# Create an annotated release tag
git tag -a v1.2.0 -m "Release 1.2.0: Add user dashboard and fix auth timeout"
# Push tags to remote
git push origin v1.2.0
# List existing tags matching a pattern
git tag -l "v1.*"
Automated Release Pipeline
When conventional commits are combined with release automation tooling, the pipeline can:
- Analyze commits since the last tag to determine the next version
- Generate or update the changelog from commit messages
- Create the git tag
- Build and publish artifacts
- Create a release entry on the hosting platform (GitHub/GitLab)
This eliminates manual version decisions and ensures the changelog stays synchronized with actual changes.
Hotfix Workflow
When a critical bug is found in production:
- Branch from the release tag (not from the development branch)
- Apply the minimal fix
- Tag the new patch release
- Merge the fix forward into the main development line to prevent regression
# Branch from the release tag
git checkout -b hotfix/fix-auth-crash v1.2.0
# After fixing and committing
git tag -a v1.2.1 -m "Hotfix: prevent auth crash on expired tokens"
git push origin v1.2.1
# Merge fix back to main
git checkout main
git merge hotfix/fix-auth-crash
Quick Reference: Common Workflow Problems
| Problem | Likely Cause | Resolution |
|---|---|---|
| Frequent merge conflicts | Long-lived branches, infrequent integration | Merge main into feature branches daily, or switch to trunk-based |
| Broken main branch | No CI on PRs, insufficient test coverage | Require passing CI before merge, add branch protection |
| Unclear release contents | No commit conventions, manual changelogs | Adopt conventional commits, automate changelog generation |
| Slow PR reviews | PRs too large, no clear ownership | Set size guidelines, configure CODEOWNERS, use stacked PRs |
| Accidental commits to main | No branch protection | Enable branch protection rules, require PR reviews |
Reference Files
| Reference | Contents |
|---|---|
| Branching Strategies | Trunk-based, GitHub Flow, Git Flow, GitLab Flow - mechanics, feature flags, comparison matrix |
| Commit Conventions | Conventional commits format, scope patterns, semantic versioning, changelog automation, git hooks |
| PR Patterns | Size guidelines, description templates, CODEOWNERS, merge strategies, branch protection, stacked PRs |
Integration with Other Skills
| Situation | Recommended Skill |
|---|---|
| Setting up CI/CD pipelines for branch protection | Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for testing strategies |
| API versioning aligned with git release tags | Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for API design principles |
| Coordinating releases across microservices | Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for microservices patterns |
| Sprint-aligned release planning | Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for scrum workflows |
What ships with it: 3 files
23.1 KB alongside SKILL.md
references/
- branching-strategies.md8.2 KB
- commit-conventions.md7.1 KB
- pr-patterns.md7.8 KB
Gives 1 of the 12 instructions most pr commit review skills give in ~2.1k tokens
Counted across 1,055 of the 1,911 authors here whose files we hold, read 2026-09-06
- Use conventional commit message formathere, and in 150 of 1055, across 145 files
- Announce skill usage at startin 78 of 1055
- Use imperative mood for commit descriptionsin 54 of 1055, across 51 files
- Add directory to gitignore if not ignoredin 52 of 1055, across 41 files
- Use imperative mood for commit subjectin 52 of 1055
- Run tests to verify clean baselinein 42 of 1055, across 32 files
- Push branch to originin 40 of 1055, across 38 files
- Verify worktree directory is ignored before creationin 39 of 1055, across 32 files
- Delete branches after mergingin 38 of 1055, across 30 files
- Create worktree with new branchin 37 of 1055, across 32 files
- Wrap body text at 72 charactersin 36 of 1055, across 34 files
- Auto-detect and run project setupin 35 of 1055, across 27 files
Said here and by no other author read
- use feature branches for pull request gates
- address one concern per pull request
- branch hotfixes from the release tag
- enable branch protection rules
- require passing continuous integration before merging
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.