SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscodeguard-git-branch

codeguard-git-branch

Deployment & operations

View repository

Updated 10-15 21:47

About this skill

Git Branching Conventions (Integration of 7 Mainstream Models)

Capability Boundaries

✅ Strengths

  1. Turn team wiki conventions into enforceable gates (regex/commands)
  2. Full coverage of mainstream styles, giving AI-written work a documented basis
  3. Clear integration paths with pre-commit / CI

⚠️ Prerequisites

  1. git; some tools need to be prepared according to installation instructions (commitlint / pre-commit framework)

❌ Out of Scope

  1. Code content review (lint-level matters belong to the corresponding language skill)
  2. commit message format → codeguard-git-commit

Basis: PartMe.AI Git Conventions wiki (GitLab branch conventions / Git workflow / Gitflow / Gitflow+) + mainstream industry practices. For the full comparison of the seven models, see references/branch-models-comparison.md。

1. First identify which model the current project uses

git branch -r Feature determination:

Feature Model
Has develop + release/* + hotfix/* Gitflow / Gitflow+(has a test branch = team Gitflow+)
Only main(or master) + many feature/* short-lived branches GitHub Flow or Trunk-Based(depending on branch lifespan and PR frequency)
Has main + production / staging / pre-prod and other environment branches GitLab Flow (environment branch style)
Has main + release/v* or release/x.y Release Flow or GitLab Flow (release branch style)
Has env/uat、env/production、*-stable GitLab branch conventions (team variant)

If it cannot be identified, ask the user; before AI creates a branch on its own, it must first follow the naming gates in Section 5.

2. Quick Reference for the Seven Models

1. Gitflow (Vincent Driessen classic)

master ──────────●──────────●────────   （每合并必打 tag）
                   \        /
develop ──●──●──●──●──●──●──────────
            \       │      \
feature ─────●──────●       \── release ──●──→ master
hotfix（线上 Bug）── 从 master 拉出 ── 合回 master + develop
  • Long-lived branches:master(only accepts merges, must be tagged),develop
  • Temporary branches:feature/*、release/*、hotfix/*
  • Flow: feature → develop → release → master; hotfix → master + develop
  • Suitable for: products with a clear release cycle and multiple versions maintained in parallel

2. Gitflow+ (team variant in use)

Based on standard Gitflow, add a test branch：

master ← release ← test ← develop ← feature
hotfix → master（同时进 develop，升补丁版本打 tag）
  • test ← develop 或测试通过的 feature; testing requests go through the test branch
  • Team naming conventions:feature/{version}_{function}_{author}_{datetime} Example:feature/1.1.0_video_a_20200806、fix/1.1.0_video_upload_bug_alicfeng_20200808

3. GitLab branch conventions (team variant)

Branch Naming Environment
Mainline Consistent with the default branch —
Feature feature/* —
Release *-stable PROD
Environment env/uat、env/production DEV/TEST/PRE
  • Merge direction restrictions: currently feature/ → mainline*; for the rest, follow the repository's MR settings

4. GitHub Flow (minimalist)

main ──●──●──●──●──●──   （main 永远可部署）
         \  /
feature ──●──            （短命分支 + PR 评审 + 合并即部署）
  • A single long-lived branch main, always kept deployable
  • All work: create branch → commit → open PR → review → merge → deploy
  • Suitable for: continuous web deployment, small teams, SaaS

5. GitLab Flow

GitHub Flow + any one of the following extensions:

  • Environment branch style：main → staging → production(code flows only downstream; for emergency fixes, use cherry-pick)
  • Release branch style：main → release/*(Create a release branch before release; only bug fixes go in)
  • Core principle upstream-first: Any fix is first merged into main (upstream), then flows down to environment/release branches

6. Trunk-Based Development (TBD)

trunk/main ──●●●●●●●●●●●●●   （所有人高频直接提交或 <2 天短命分支）
                ↘ feature flag 控制未完成功能
  • Each person merges to trunk at least once per day; branch lifetime < 2 days
  • Use feature flag to hide unfinished features instead of isolating them in branches
  • Supporting requirements: strong automated testing + every commit is releasable
  • Suitable for: teams with mature CI/CD and high-frequency releases (Google/Meta style)

7. OneFlow (modern Gitflow alternative)

main ──●──────●──────●──────   （唯一长期分支）
         \       \
feature ──●       \── release（可选）──→ main + tag
hotfix ──────────────────→ main + tag
  • Only main exists long-term;develop is removed
  • Features branch off from main; releases can go through a release branch (optional) or tag directly from main
  • Supports both merge and rebase styles (the team chooses one and unifies on it)

8. Release Flow (Microsoft style)

main ──●──●──●────────●──   （一切开发在 main）
            \         \
release/v1.0 ──●←cherry-pick
  • At release time, create release/v{major.minor}from main; bug fixes are made in main and cherry-picked back to the release branch
  • The release branch only lives until that version is no longer maintained

III. Branch naming gates (AI-created branches must comply)

Model Naming
Gitflow / Gitflow+ feature/{version}_{function}_{author}_{datetime}；fix/...；hotfix/...；release/{version}
GitHub Flow / TBD {type}/{issue号}-{短描述}, such as feature/128-user-auth、fix/305-null-check
GitLab branch conventions feature/*、*-stable、env/{name}
Release Flow Functionality same as TBD; release release/v{major.minor}

Rules for AI-created branches:

  1. First git branch -r identify the model, then name according to the table above
  2. When author/datetime is needed, obtain it from the user or git log,do not fabricate
  3. version takes git describe --tags --abbrev=0 or user-specified

IV. Merge direction gates

Model Gate
Gitflow / Gitflow+ master ← only release/hotfix (must tag); feature → develop; develop → test (Gitflow+)
GitHub Flow feature → main; main is always deployable
GitLab Flow Downstream only: main → staging → production; upstream-first
TBD short-lived branches → main; direct push requires team agreement
OneFlow feature → main；release → main；hotfix → main
Release Flow All development is in main; release/* only receives cherry-picks
GitLab branch conventions feature/* → trunk

V. Merge strategy (merge vs squash vs rebase)

Strategy History Applicable to
Merge commit（--no-ff） Preserves the full branch shape + merge nodes Gitflow family (team default); master merge
Squash merge Compress into a single commit GitHub Flow / TBD (keep main as one commit per feature)
Rebase + fast-forward Linear history OneFlow / TBD; sync upstream within feature

AI rule: first look at the project's existing history (git log --oneline --graph -20) to identify conventions; when unsure, ask the user,do notarbitrarily rebase a pushed shared branch.

VI. General workflow habits

  1. High-frequency fine-grained commits; commit upon completion to make it easier to locate issues and resolve conflicts
  2. Self-test/unit tests pass before commit
  3. If there are changes, commit at least once a day
  4. Delete the branch after a feature is merged (whoever owns the branch deletes it)
  5. hotfix must be backported to both trunk and development lines, and the patch version must be bumped and tagged
  6. Every release merge on master/main must be tagged, and the tag message must state the update content.

7. AI Behavior Checklist

  • Before creating a branch: identify the model → create it according to the corresponding naming format
  • Before merging: confirm the direction is within the gate table; for master/main merges, confirm the version number and tag plan
  • Before rebasing: confirm the branch has not been pulled by others
  • Strictly prohibited: committing directly to master/main (unless TBD and the team allows it); mixing naming across models; accepting new feature work on a release branch

Out of Scope (when it should not be used)

  • When you only need to write a commit message, hand off to the codeguard-git-commit skill.
  • When the repository already has a clear model, but the user asks to switch to a different team workflow; this is a governance decision and should not be done arbitrarily by the skill.
  • When the target is already-pushed shared history, but there is no team confirmation and recovery plan.

Data and Security

By default, only local Git metadata is read; source code and credentials are not collected, uploaded, sent, or stored. Creating/switching branches, rebase, merge, push, and tag are all independent write operations and must be executed with user authorization and within scope.

Evidence-Based Workflow

Step 1: Read repository rules

Review AGENTS/CONTRIBUTING/team docs, the default branch, protection rules, and release configuration.

Step 2: Identify the current model

Use remote branches, recent history, and release branches as evidence; when a unique determination cannot be made, list the candidates and their differences.

Step 3: Validate naming input

Obtain version/author/description from issues, tags, Git configuration, or the user; do not fabricate missing values.

Step 4: Check flow direction and history safety

Confirm that source/target conform to the model, and confirm the branch is not shared before rebasing.

Step 5: Output a plan or execute authorized actions

Report the model, evidence, naming, flow direction, merge strategy, and recovery method.

Gotchas

  1. The presence of develop does not necessarily mean Gitflow: the release/hotfix flow must also be checked.
  2. Environment branches may prohibit backflow: code in GitLab Flow usually flows only to downstream environments.
  3. Rebase rewrites SHAs: shared branches must not be rebased/force-pushed arbitrarily.
  4. Squash loses fine-grained history: applicability depends on the team's audit and rollback strategy.
  5. Tags are not an automatic conclusion: version number and signing requirements must come from repository rules.
  6. Worktrees and submodules have independent states: do not infer the inner repository from the outer branch.

Load resources on demand

  • When comparing models, read references/branch-models-comparison.md。
  • When deciding or handing off, read references/rules/decision-contract.md and references/operations/evidence-playbook.md。
  • Only open examples/ examples that match the current task.