Git Workflow and Versioning

Git Workflow and Versioning

- Dev branches are costs. Every day a branch lives, it accumulates merge risk

Category: content-creation Source: addyosmani/agent-skills

What Is This

The "Git Workflow and Versioning" skill is a structured approach to managing code changes using Git. This skill defines best practices for organizing commits, handling branches, and maintaining a clean project history. It is designed for use whenever you make code changes, commit, create or merge branches, resolve conflicts, or coordinate work across multiple contributors or parallel efforts. The core of this skill is the principle that disciplined use of Git is essential for keeping code reviewable, reversible, and manageable-especially as teams and AI agents generate code at a rapid pace.

Why Use It

Modern software projects demand rapid iteration, collaboration, and reliability. Without a well-defined workflow, codebases become difficult to maintain, and integration becomes risky. Every additional day a branch remains unmerged increases the likelihood of merge conflicts and integration failures. This skill emphasizes the importance of short-lived branches and trunk-based development to minimize these risks. Research from the DORA (DevOps Research and Assessment) group shows that teams practicing trunk-based development, with frequent merges to a deployable main branch, consistently achieve higher performance and stability.

In essence, this skill helps you:

  • Keep the main branch always deployable and production-ready
  • Reduce the risk and complexity of merging long-lived branches
  • Ensure that all changes are tracked, reviewable, and can be rolled back if necessary
  • Foster a collaborative environment where parallel work does not compromise code quality

How to Use It

1. Commit Discipline

Treat commits as atomic save points. Each commit should represent a logical, self-contained change. Use descriptive commit messages that explain why a change was made, not just what was changed.

Example:

git add src/payment.js
git commit -m "Fix rounding error in payment calculation"

2. Short-Lived Feature Branches

When developing a new feature or fixing a bug, create a branch from the latest main. Keep this branch "short-lived"-typically merged back into main within 1-3 days.

Example:

git checkout main
git pull
git checkout -b feature/upgrade-payment-api
## ... make changes ...
git add .
git commit -m "Upgrade payment API to v2"
git checkout main
git pull
git merge feature/upgrade-payment-api
git push

3. Keep main Always Deployable

After merging a branch, ensure that main passes all tests and is ready for deployment. Never break the build.

4. Resolve Conflicts Early

Regularly sync your feature branch with main to catch and resolve conflicts early, before they become unmanageable.

Example:

git checkout feature/upgrade-payment-api
git fetch origin
git rebase origin/main
## Resolve any conflicts, then continue rebase
git push --force

5. Avoid Long-Lived Development Branches

Long-lived branches accumulate "merge risk." As the base branch evolves, the longer your branch lives, the more likely you are to encounter complex conflicts. Merge or rebase frequently-ideally daily.

6. Descriptive Branch Naming

Use branch names that clearly indicate their purpose. For example:

  • feature/add-login-form
  • bugfix/fix-null-pointer
  • hotfix/rollback-broken-deploy

7. Versioning

Tag releases in Git to mark stable points in your project history.

Example:

git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

When to Use It

This skill should be used for every code change. Whether you are fixing a typo, implementing a major feature, or merging contributions from multiple team members or AI agents, apply these principles. Specifically, use this workflow when:

  • Starting a new feature or experiment
  • Fixing bugs or making hotfixes
  • Resolving merge conflicts
  • Organizing or reviewing code
  • Tagging releases for deployment or rollback

Important Notes

  • Dev branches are costs: Every day a branch exists, it accumulates merge risk and increases the chance of conflicts and integration headaches.
  • Atomic commits: Smaller, focused commits are easier to review, debug, and revert.
  • Descriptive messages and branches: Clarity in naming and commit messages makes history useful for everyone.
  • Adaptability: While trunk-based development is recommended, these practices can be adapted to other branching strategies. The discipline in versioning and commit hygiene is more important than the specific model.
  • Continuous integration: Automated testing and CI pipelines should run on every push and merge to main, ensuring that the branch remains deployable.
  • Documentation: Use commit messages and tags as documentation. This audit trail is critical for understanding project evolution and debugging regressions.

By following the Git Workflow and Versioning skill, you reduce the risk and cost of integration, improve team velocity, and maintain a history that supports rapid, reliable software delivery.