Git branching model
Feature branches merging through develop to main.
Every team has a branching convention; far fewer have it written down where a
new engineer can find it. This gitGraph documents a lightweight, widely used
model in one screen: feature branches cut from develop, merged back after
review, and a release to main tagged v1.0.0. The diagram shows the part
that text descriptions always fumble — which branch you cut from, which
direction merges flow, and where the tag lands.
Because Mermaid gitGraphs are scripted with the same vocabulary as git itself
(branch, checkout, merge, commit), the diagram doubles as a worked
example: a junior engineer can read it top to bottom as the sequence of
commands a feature actually goes through.
When to use this template
- README and contributing guides — replace the paragraph explaining your branch conventions with a diagram that renders natively on GitHub and GitLab.
- Onboarding new engineers — the first question on day one is "where do I branch from and where do I merge to?"; this answers it without a meeting.
- Workflow change proposals — when arguing for or against git flow, trunk-based, or release branches, diagram the candidate models side by side instead of debating in the abstract.
How to adapt it
Rewrite the branch names and commits to mirror your actual conventions. Common extensions:
- Add a hotfix branch cut from
mainand merged back into bothmainanddevelop— the flow most often gotten wrong in practice. - Show a release branch (
release/1.1) if you stabilize releases separately from ongoing develop work. - Add a second feature branch in parallel to show how concurrent work integrates, including which feature merges first.
You can also restructure the graph in the visual editor — it regenerates clean Mermaid code, so the polished diagram pastes straight into your CONTRIBUTING.md.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
gitGraph
commit id: "init"
branch develop
checkout develop
commit id: "setup"
branch feature/login
checkout feature/login
commit id: "login form"
commit id: "tests"
checkout develop
merge feature/login
checkout main
merge develop tag: "v1.0.0"
checkout develop
commit id: "next work"
Frequently asked questions
- How do I draw a git branch diagram in Mermaid?
- Use the `gitGraph` diagram type and script the history with four commands: `commit` (optionally with `id: "label"`), `branch` to create and switch to a new branch, `checkout` to move between branches, and `merge` to join them. Mermaid draws the lanes, dots, and merge arrows automatically, so the diagram is just a readable transcript of the workflow.
- What branching strategy does this template show?
- A lightweight git-flow variant: `main` holds released code, `develop` is the integration branch, and feature branches like `feature/login` are cut from develop and merged back after review. Releases happen by merging develop into main with a version tag. It's the middle ground between full git-flow (with release and hotfix branches) and trunk-based development.
- Should I use git flow or trunk-based development?
- It depends on release cadence. Trunk-based development suits teams deploying continuously behind feature flags — short-lived branches merge straight to main. Git-flow-style models suit versioned releases, mobile apps, or environments needing a stabilization window. Whichever you pick, document it as a diagram in the README; most branching confusion comes from conventions living only in senior engineers' heads.
- Can I show release tags in a Mermaid gitGraph?
- Yes — append `tag: "v1.0.0"` to a commit or merge command, exactly as this template does on the merge into main. Tags render as labeled badges on the commit, which makes release points stand out in the history. You can tag any commit, so hotfix releases and release candidates (`tag: "v1.1.0-rc1"`) work the same way.