Conventional Branch

Conventional Branch 1.1.0

Summary

Conventional Branch refers to a structured and standardized naming convention for Git branches which aims to make branch more readable and actionable. We’ve suggested some branch prefixes you might want to use but you can also specify your own naming convention. A consistent naming convention makes it easier to identify branches by type.

Key Points

1. Purpose-driven Branch Names: Each branch name clearly indicates its purpose, making it easy for all developers to understand what the branch is for.
2. Integration with CI/CD: By using consistent branch names, it can help automated systems (like Continuous Integration/Continuous Deployment pipelines) to trigger specific actions based on the branch type (e.g., auto-deployment from release branches).
3. Team Collaboration: It encourages collaboration within teams by making branch purpose explicit, reducing misunderstandings, and making it easier for team members to switch between tasks without confusion.

Specification

Branch Naming Prefixes

The branch specification supports the following prefixes and should be structured as:

<type>/<description>

Purpose Prefixes — describe the intent of the work:

• feature/ (or feat/): For new features (e.g., feature/add-login-page, feat/add-login-page)
• bugfix/ (or fix/): For bug fixes (e.g., bugfix/fix-header-bug, fix/header-bug)
• hotfix/: For urgent fixes (e.g., hotfix/security-patch)
• release/: For branches preparing a release (e.g., release/v1.2.0)
• chore/: For non-code tasks like dependency, docs updates (e.g., chore/update-dependencies)

AI Agent Source Prefixes — identify branches generated by AI coding agents:

Trunk branches (main, master, develop) do not use a prefix.

Basic Rules

1. Use Lowercase Alphanumerics, Hyphens, and Dots: Always use lowercase letters (a-z), numbers (0-9), and hyphens (-) to separate words. Avoid special characters, underscores, or spaces. For release branches, dots (.) may be used in the description to represent version numbers (e.g., release/v1.2.0).
2. No Consecutive, Leading, or Trailing Hyphens or Dots: Ensure that hyphens and dots do not appear consecutively (e.g., feature/new--login, release/v1.-2.0), nor at the start or end of the description (e.g., feature/-new-login, release/v1.2.0.).
3. Keep It Clear and Concise: The branch name should be descriptive yet concise, clearly indicating the purpose of the work.
4. Include Ticket Numbers: If applicable, include the ticket number from your project management tool to make tracking easier. For example, for a ticket issue-123, the branch name could be feature/issue-123-new-login.

Formal Grammar

The following Augmented Backus-Naur Form (ABNF) grammar formally defines valid branch names:

branch-name     = trunk-branch / prefixed-branch
trunk-branch    = "main" / "master" / "develop"
prefixed-branch = type "/" description
type            = "feature" / "feat" / "bugfix" / "fix"
                / "hotfix" / "release" / "chore"
                / "ai" / "copilot" / "cursor"
                / "claude" / "codex"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; lowercase a-z
DIGIT           = %x30-39   ; 0-9

Note: Consecutive hyphens or dots, and hyphens or dots at the start or end of the description, are not permitted.

Examples

Conclusion

• Clear Communication: The branch name alone provides a clear understanding of its purpose the code change.
• Automation-Friendly: Easily hooks into automation processes (e.g., different workflows for feature, release, etc.).
• Scalability: Works well in large teams where many developers are working on different tasks simultaneously.

In summary, conventional branch is designed to improve project organization, communication, and automation within Git workflows.

Tooling

Use these tools to adopt and enforce Conventional Branch in your project:

• commit-check: Check branch names, commit messages, and related Git metadata locally.
• commit-check-action: Validate branch names automatically in GitHub Actions.
• Conventional Branch Skill: Teach AI coding assistants how to create valid Conventional Branch names.

Install the skill with:

npx skills add conventional-branch/conventional-branch --skill conventional-branch

FAQ

How does Conventional Branch relate to Conventional Commits?

Conventional Branch is inspired by Conventional Commits and follows a similar philosophy: bring human- and machine-readable structure to Git metadata. While Conventional Commits standardizes commit messages, Conventional Branch standardizes branch names. The two specifications complement each other naturally.

Why aren’t branch types as detailed as Conventional Commits (e.g., build, ci, docs, style, refactor)?

Branches are different from commits—they are temporary and mainly used until merged. Introducing too many types for branches would be unnecessary and would make them harder to manage and remember.

Can I define my own branch types beyond the ones listed?

Yes. The specification defines a recommended set of types, but teams can define additional custom types to fit their workflow. It is important, however, to document custom types clearly so that all team members and automated tooling are aware of them.

What are the main differences between v1.1.0 and v1.0.0?

v1.1.0 adds AI Agent Source Prefixes as the primary new feature (see the next FAQ entry for why these were introduced). It also ships a versioned website with a version switcher so users can browse both the v1.0.0 and v1.1.0 specifications. All existing v1.0.0 branch names remain fully valid — no breaking changes.

Why add AI Agent Source Prefixes?

AI coding agents (GitHub Copilot, Cursor, Claude Code, OpenAI Codex, etc.) are increasingly used to generate code and create pull requests. Each agent uses its own branch prefix (e.g., copilot/, cursor/). By standardizing these prefixes in the Conventional Branch specification, we enable:

1. Quick identification — reviewers and tools can immediately recognize AI-generated PRs
2. Tool validation — tools like commit-check can validate AI agent branches against the spec
3. A registration standard — new AI agents can adopt a documented prefix instead of inventing ad-hoc patterns

The ai/ generic prefix is available for any AI agent that does not have a dedicated prefix, or for teams who prefer a vendor-neutral identifier. This is the key new feature released in v1.1.0 — for a full summary of changes between versions, see the FAQ entry above.

How should I handle long-lived branches like develop or staging?

Long-lived integration or environment branches that are part of the core specification (see the trunk-branch rule in the grammar) such as main, master, or develop are treated as trunk branches and do not require a prefix. Teams may additionally choose to treat other long-lived branches (for example, staging or production) as “trunk-like” branches by convention, but these are team-specific extensions outside the formal grammar. In all cases, such branches should be named consistently across your project.

What tools can be used to automatically identify if a team member does not meet this specification?

You can use commit-check to check branch specification or commit-check-action if your codes are hosted on GitHub.