Why is Git Specification Necessary?¶

In team collaboration without specifications, Git version control often becomes a “mess”: someone creates branches randomly, someone writes vague commit messages, there are numerous conflicts during code merging, and finding a historical version to fix a bug requires sifting through all commit records… The result is low efficiency and chaotic collaboration.

A unified Git specification is like a “traffic rule” for team collaboration, making everyone’s operations clear and predictable, reducing communication costs, and facilitating code tracking and problem location. Next, we’ll start with the most basic aspects of “branch naming” and “commit messages” to gradually establish a team’s Git collaboration specification.

I. Branch Naming Specification: Labeling Each Branch¶

Branches are a core feature of Git. A standardized branch naming convention allows everyone to quickly understand: What is this branch for? Where does it originate? Where is it going?

1. Common Branch Types (Essential for Team Collaboration)¶

• Main Branch (Master/Main) : The “source” of the project, kept absolutely stable. It only accepts merges and no direct code changes. Usually corresponds to the production environment and is never modified once released.
• Development Branch (Develop) : Integrates ongoing development features. All features are merged here for testing and pre-release.
• Feature Branch (Feature) : Created for new features or large requirements, branched from the Develop branch and merged back into Develop upon completion.
• Bugfix Branch (Bugfix) : For fixing bugs found during development, branched from Develop and merged back after resolution.
• Hotfix Branch (Hotfix) : For urgent production bugs, branched from Master. After fixing, it is merged into both Master and Develop.

2. Naming Format (Mandatory Team Uniformity)¶

• Feature Branch : feature/[RequirementID]-[Brief Feature Description]
  Example: feature/123-user-login-form (Requirement ID 123, feature: user login form)
• Bugfix Branch : bugfix/[BugID]-[Bug Description]
  Example: bugfix/456-fix-login-validation (Bug ID 456, fixing login validation issue)
• Hotfix Branch : hotfix/[BugID]-[Issue Description]
  Example: hotfix/789-fix-payment-crash (Fixing production payment crash issue)
• Main and Development Branches : Typically fixed names (Master/Main, Develop) without additional naming rules.

Tips:¶

• Branch names should be concise but include key information (e.g., Requirement ID/Issue ID) for easy search using tools like GitLab/GitHub.
• Avoid Chinese characters and special symbols (e.g., #, $) to prevent issues with different system recognition.

II. Commit Message Specification: Making Every “Commit” Meaningful¶

Commit messages are the “manual” for code. Good commit messages help you (and teammates) quickly identify: What was changed? Why was it changed?

1. Why Standardize Commit Messages?¶

• Avoid “random changes”: Others (or future you) can immediately understand the purpose of a specific modification.
• Facilitate version management: Use tools like Git log to filter specific types of commits (e.g., only “fix” related ones).
• Support automation tools: Standardized commit messages can be automatically used to generate change logs (e.g., Changelog).

2. Most Common “Conventional Commits” Specification¶

Format: Type: Short Subject (under 50 characters) [Optional: Detailed Description]

Types (Mandatory):¶

• feat: New feature (e.g., adding user registration, homepage carousel)
• fix: Bug fix (e.g., “user login crashes” or “button not responding”)
• docs: Documentation update (e.g., README, API comments)
• style: Code format adjustment (e.g., indentation, spaces, no logic changes)
• refactor: Code refactoring (e.g., optimizing function logic without adding features/fixing bugs)
• perf: Performance optimization (e.g., reducing load time, improving query speed)
• test: Testing-related (e.g., adding unit tests, fixing test cases)
• chore: Routine tasks (e.g., dependency updates, version number changes, temporary file cleanup)

Examples:¶

• ✅ Standard: feat: add user registration form
  (New feature: adding user registration form)
• ✅ Standard: fix: resolve login button unresponsive issue
  (Bug fix: resolving login button unresponsive issue)
• ✅ With Detailed Description: docs: update API documentation
  (Detailed: Updating “Get Token” steps in user manual)
• ❌ Non-Standard: Some changes (Completely incomprehensible to others)

3. How to Remember the Specification?¶

• Lowercase Type Initials: Use fix instead of Fix (consistency).
• Concise Subject: Use imperative mood (e.g., “add” instead of “added”).
• Multiline Descriptions: Separate detailed descriptions with a blank line for readability.

III. Specification Implementation: Using Common Git Commands¶

1. Create a Branch (According to Specification)¶

# Ensure the develop branch is up-to-date
git checkout develop
git pull origin develop

# Create a feature branch (Example: Requirement ID 123, feature "user login form")
git checkout -b feature/123-user-login-form

2. Commit Code (According to Specification)¶

# Check modified files
git status

# Add all changes (or specific files)
git add .  # Add all new/modified files

# Commit (Example: Adding user login form)
git commit -m "feat: add user registration form"

# Push the branch to the remote repository
git push origin feature/123-user-login-form

3. Merge into Development Branch (During Collaboration)¶

# Switch to develop branch and pull the latest code
git checkout develop
git pull origin develop

# Merge the feature branch
git merge feature/123-user-login-form

# (Optional) Delete the merged branch
git branch -d feature/123-user-login-form

4. Resolve Conflicts (Key for Specification Implementation)¶

If conflicts occur during merging, don’t panic! Follow these steps:
1. Pull the latest code: Ensure your local develop branch is up-to-date.
2. Manually modify conflict files: Open the conflicted file (Git marks conflict regions, e.g., <<<<<<< HEAD).
3. Negotiate and resolve: Communicate with teammates to confirm the final code logic.
4. Mark conflicts as resolved:

   git add .  # After resolving all conflicts
   git commit -m "merge: resolve conflicts in login form"

IV. How to Enforce Team Compliance?¶

1. Emphasize during code review: Check branch names and commit messages for compliance before merging.
2. Use auxiliary tools:
   - Use pre-commit hooks to automatically check commit messages (e.g., requiring feat/fix).
   - Clearly specify the specification in PR templates on GitHub/GitLab.
3. Reach team consensus: Explain the specification to new members during onboarding and review it regularly (e.g., weekly 10-minute meetings).

Summary¶

The core of Git specification is “clarity and traceability”: Branch naming clarifies collaboration goals, while commit messages clarify modification purposes. At first, it may seem cumbersome, but once habits are formed, code becomes like an “indexed ledger”—any problem can be quickly traced to its source, and team collaboration efficiency naturally improves.

Start using standardized branch names and commit messages from today for your first line of code!