Merge pull request #3010 from mermaid-js/GitGraph_mainBranchOrdering

Added support to change the position of the main branch

docs/README.md

@@ -111,28 +111,20 @@ Class08 <--> C2: Cool label
 
 ![Class diagram](img/class.png)
 
-### Git graph - :exclamation: experimental
-
-```mmd
-gitGraph:
-options
-{
-    "nodeSpacing": 150,
-    "nodeRadius": 10
-}
-end
-commit
-branch newbranch
-checkout newbranch
-commit
-commit
-checkout master
-commit
-commit
-merge newbranch
-
+### Git graph
+
+```mermaid-example
+    gitGraph
+       commit
+       commit
+       branch develop
+       commit
+       commit
+       commit
+       checkout main
+       commit
+       commit
 ```
-![Git graph](img/git.png)
 
 ### [Entity Relationship Diagram - :exclamation: experimental](./entityRelationshipDiagram.md)
 

docs/_sidebar.md

@@ -14,7 +14,7 @@
   - [Gantt](gantt.md)
   - [Pie Chart](pie.md)
   - [Requirement Diagram](requirementDiagram.md)
-  - [Gitgraph (Git) Diagram 🔥🔥🔥](gitgraph.md)
+  - [Gitgraph (Git) Diagram 🔥](gitgraph.md)
   - [Other Examples](examples.md)
 
 - ⚙️ Deployment and Configuration

docs/gitgraph.md

@@ -187,6 +187,7 @@ In Mermaid, you have the option to configure the gitgraph diagram. You can confi
 - `showBranches` : Boolean, default is `true`. If set to `false`, the branches are not shown in the diagram.
 - `showCommitLabel` : Boolean, default is `true`. If set to `false`, the commit labels are not shown in the diagram.
 - `mainBranchName` : String, default is `main`. The name of the default/root branch.
+- `mainBranchOrder` : Position of the main branch in the list of branches. default is `0`, meanig, by default `main` branch is the first in the order.
 
 Let's look at them one by one.
 ## Hiding Branch names and lines
@@ -290,7 +291,7 @@ Usage example:
         merge release
  ```
 
-## Customizing the main/default branch name
+## Customizing main branch name
 Sometimes you may want to customize the name of the main/default branch. You can do this by using the `mainBranchName` keyword. By default its value is `main`. You can set it to any string using directives.
 
 Usage example:
@@ -312,13 +313,60 @@ Usage example:
         merge MetroLine3
         commit id:"Miami"
         commit id:"Washington"
-        merge MetroLine2
+        merge MetroLine2 tag:"MY JUNCTION"
         commit id:"Boston"
         commit id:"Detroit"
         commit type:REVERSE id:"SanFrancisco"
  ```
 Look at the imaginary railroad map created using Mermaid. Here, we have changed the default main branch name to `MetroLine1`.
 
+## Customizing branch ordering
+In Mermaid, by default the branches are shown in the order of their defintion or appearance in the diagram code.
+
+Sometimes you may want to customize the order of the branches. You can do this by using the `order` keyword next the branch definiton. You can set it to a positive number.
+
+Mermaid follows the given precendence order of the `order` keyword.
+- Main branch is always shown first as it has default order value of `0`. (unless its order is modified and changed from `0` using the `mainBranchOrder` keyword in the config)
+- Next, All branches without an `order` are shown in the order of their appearance in the diagram code.
+- Next, All branches with an `order` are shown in the order of their `order` value.
+
+To fully control the order of all the branches, you must define `order` for all the branches.
+
+Usage example:
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%%
+      gitGraph
+      commit
+      branch test1 order: 3
+      branch test2 order: 2
+      branch test3 order: 1
+
+ ```
+Look at the diagram, all the branches are following the order defined.
+
+
+Usage example:
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchOrder': 2}} }%%
+      gitGraph
+      commit
+      branch test1 order: 3
+      branch test2
+      branch test3
+      branch test4 order: 1
+
+ ```
+Look at the diagram, here, all the branches without a specified order are drawn in their order of definition.
+Then, `test4` branch is drawn becuase the order of `1`.
+Then, `main` branch is drawn becuase the order of `2`.
+And, lastly `test1`is drawn becuase the order of `3`.
+
+NOTE: Becuase we have overriden the `mainBranchOrder` to `2`, the `main` branch is not drawn in the begining, instead follows the ordering.
+
+
+
+Here, we have changed the default main branch name to `MetroLine1`.
+
 ## Themes
 Mermaid supports a bunch of pre-defined themes which you can use to find the right one for you. PS: you can actually override an existing theme's variable to get your own custom theme going. Learn more about theming your diagram [here](./theming.md).
 

src/defaultConfig.js

@@ -1055,6 +1055,7 @@ const config = {
       y: 0,
     },
     mainBranchName: 'main',
+    mainBranchOrder: 0,
     showCommitLabel: true,
     showBranches: true,
   },

src/diagrams/git/gitGraphAst.js

@@ -13,19 +13,17 @@ import {
 } from '../../commonDb';
 
 let mainBranchName = getConfig().gitGraph.mainBranchName;
+let mainBranchOrder = getConfig().gitGraph.mainBranchOrder;
 let commits = {};
 let head = null;
 let branchesConfig = {};
-branchesConfig[mainBranchName] = { name: mainBranchName, order: 0 };
+branchesConfig[mainBranchName] = { name: mainBranchName, order: mainBranchOrder };
 let branches = {};
 branches[mainBranchName] = head;
 let curBranch = mainBranchName;
 let direction = 'LR';
 let seq = 0;
 
-/**
- *
- */
 function getId() {
   return random({ length: 7 });
 }
@@ -335,10 +333,11 @@ export const clear = function () {
   commits = {};
   head = null;
   let mainBranch = getConfig().gitGraph.mainBranchName;
+  let mainBranchOrder = getConfig().gitGraph.mainBranchOrder;
   branches = {};
   branches[mainBranch] = null;
   branchesConfig = {};
-  branchesConfig[mainBranch] = { name: mainBranch, order: 0 };
+  branchesConfig[mainBranch] = { name: mainBranch, order: mainBranchOrder };
   curBranch = mainBranch;
   seq = 0;
   commonClear();

src/diagrams/git/gitGraphRenderer.js

@@ -418,7 +418,7 @@ const drawBranches = (svg, branches) => {
 
     lanes.push(pos);
 
-    let name = index === 0 ? gitGraphConfig.mainBranchName : branch.name;
+    let name = branch.name;
 
     // Create the actual text element
     const labelElement = drawText(name);