Conventional Branch

Conventional Branch 1.0.0

A specification for adding human and machine readable meaning to branch names.

Use this skill to create, revise, validate, or explain Git branch names according to Conventional Branch 1.0.0. The specification is the source of truth for the guidance below.

Summary

Conventional Branch refers to a structured and standardized naming convention for Git branches which aims to make branch names more readable and actionable. The specification suggests branch prefixes you might want to use, but teams can also specify their 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, automated systems such as Continuous Integration/Continuous Deployment pipelines can trigger specific actions based on the branch type, for example 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:

/

• Trunk branches: main, master, or develop are used without a prefix for the main development line.
• feature/ or feat/: For new features, for example feature/add-login-page or feat/add-login-page.
• bugfix/ or fix/: For bug fixes, for example bugfix/fix-header-bug or fix/header-bug.
• hotfix/: For urgent fixes, for example hotfix/security-patch.
• release/: For branches preparing a release, for example release/v1.2.0.
• chore/: For non-code tasks like dependency or docs updates, for example chore/update-dependencies.

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. Dots (.) may be used in the description, commonly to represent version numbers for release branches, for example release/v1.2.0.
2. Use exactly one slash for prefixed branches: A prefixed branch has the form /. The description does not contain additional slashes.
3. No Consecutive, Leading, or Trailing Hyphens or Dots: Ensure that hyphens and dots do not appear consecutively, for example feature/new--login or release/v1.-2.0, nor at the start or end of the description, for example feature/-new-login or release/v1.2.0..
4. Keep It Clear and Concise: The branch name should be descriptive yet concise, clearly indicating the purpose of the work.
5. Include Ticket Numbers: If applicable, include the ticket number from the 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"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; lowercase a-z
DIGIT           = %x30-39   ; 0-9

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

Examples

| Branch Name | Valid | Notes | | ----------------------------- | ----- | ------------------------------------- | | main | ✅ | Trunk branch | | master | ✅ | Trunk branch | | develop | ✅ | Trunk branch | | feature/add-login-page | ✅ | New feature | | feat/add-login-page | ✅ | Short alias for feature | | bugfix/fix-header-bug | ✅ | Bug fix | | fix/header-bug | ✅ | Short alias for bugfix | | hotfix/security-patch | ✅ | Urgent fix | | release/v1.2.0 | ✅ | Release with version | | chore/update-dependencies | ✅ | Non-code task | | feature/issue-123-new-login | ✅ | Feature with ticket number | | feature/123 | ✅ | Numeric description segment | | chore/upgrade-node-20.10.0 | ✅ | Dots allowed in a description segment | | Feature/Add-Login | ❌ | Uppercase letters not allowed | | feature/new--login | ❌ | Consecutive hyphens not allowed | | feature/-new-login | ❌ | Leading hyphen in description | | feature/new-login- | ❌ | Trailing hyphen in description | | feature/auth/login | ❌ | Only one slash is allowed | | release/v1.-2.0 | ❌ | Hyphen adjacent to dot | | fix/header bug | ❌ | Spaces not allowed | | fix/header_bug | ❌ | Underscores not allowed | | unknown/some-task | ❌ | Unknown prefix type |

Practical guidance when answering users

• Prefer to output only the branch name when the user asks for a branch name and does not ask for explanation.
• If the user asks to validate, explain, or fix an existing branch name, state whether it conforms and give a corrected version when needed.
• Prefer lowercase everywhere. Use hyphens to separate words. Do not use spaces, underscores, uppercase letters, or special characters.
• Choose the branch prefix from the formal types when possible: feature, feat, bugfix, fix, hotfix, release, or chore.
• Use trunk branch names main, master, or develop without a prefix when the user is naming the main development branch.
• Include a ticket number when the user provides one or when it is clearly applicable, using lowercase alphanumerics and hyphens, for example feature/issue-123-new-login. Lowercase user-supplied ticket identifiers, for example ABC-123 becomes abc-123.
• Keep branch names clear and concise: include enough context to communicate the purpose, but avoid unnecessary words.
• When the user's requested type is outside the formal grammar, explain that teams may define their own naming conventions, but the formal Conventional Branch grammar only includes the listed types and trunk branches. Do not invent prefixes such as docs/, test/, or refactor/ as formal Conventional Branch names; if the work does not fit another formal type, prefer chore/ or ask the user which team-specific type they want.
• For long-lived integration or environment branches outside main, master, or develop, explain that treating names such as staging or production as trunk-like branches is a team-specific extension outside the formal grammar.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sherif-fanous
• Source: sherif-fanous/skills
• License: MIT

Install and usage instructions live in the source repository linked above.