gitgraph

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package gitgraph is mermaid git graph diagram builder.

Ref. https://mermaid.js.org/syntax/gitgraph.html

Errors are recorded rather than returned from every call: the chain runs to the end and the error surfaces from Build. A nil writer and a writer that refuses the diagram are both reported rather than causing a panic, and String returns the diagram without needing a writer at all.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BranchOption 

type BranchOption func(*branchConfig)

BranchOption sets branch options.

Example

ExampleBranchOption shows what a BranchOption is: a function that changes how a branch is written, passed to Branch after its name. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	options := []gitgraph.BranchOption{gitgraph.WithBranchOrder(2)}

	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("release", options...).
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch release order: 2

func WithBranchOrder 

func WithBranchOrder(order int) BranchOption

WithBranchOrder sets the branch order. Order must be zero or greater.

Example

ExampleWithBranchOrder says where a branch is drawn against the others, which is how a diagram keeps the important branch at the top. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("release", gitgraph.WithBranchOrder(1)).
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch release order: 1

type CherryPickOption 

type CherryPickOption func(*cherryPickConfig)

CherryPickOption sets cherry-pick options.

Example

ExampleCherryPickOption shows what a CherryPickOption is: a function that changes how a cherry pick is written, passed to CherryPick after the commit it names. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	options := []gitgraph.CherryPickOption{}

	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("develop").
		Commit(gitgraph.WithCommitID("fix")).
		Checkout("main").
		CherryPick("fix", options...).
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch develop
    commit id: "fix"
    checkout main
    cherry-pick id: "fix"

func WithCherryPickParent 

func WithCherryPickParent(parentID string) CherryPickOption

WithCherryPickParent sets the cherry-pick parent commit id.

Example

ExampleWithCherryPickParent says which parent of a merge commit a cherry pick takes, which mermaid needs when the commit being picked is a merge. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("develop").
		Commit(gitgraph.WithCommitID("work")).
		Checkout("main").
		Merge("develop", gitgraph.WithCommitID("merge")).
		Branch("release").
		CherryPick("merge", gitgraph.WithCherryPickParent("initial")).
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch develop
    commit id: "work"
    checkout main
    merge develop id: "merge"
    branch release
    cherry-pick id: "merge" parent: "initial"

type CommitOption 

type CommitOption func(*commitConfig)

CommitOption sets commit options.

Example

ExampleCommitOption shows what a CommitOption is: a function that changes how a commit is written, passed to Commit or to Merge. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	options := []gitgraph.CommitOption{
		gitgraph.WithCommitID("release"),
		gitgraph.WithCommitTag("v1.0.0"),
	}

	_ = gitgraph.NewDiagram(os.Stdout).Commit(options...).Build()

}

Output:
gitGraph
    commit id: "release" tag: "v1.0.0"

func WithCommitID 

func WithCommitID(id string) CommitOption

WithCommitID sets the commit id.

Example

ExampleWithCommitID names a commit, which is what a cherry pick and a reset refer to. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Build()

}

Output:
gitGraph
    commit id: "initial"

func WithCommitTag 

func WithCommitTag(tag string) CommitOption

WithCommitTag sets the commit tag.

Example

ExampleWithCommitTag puts a tag on a commit, drawn beside it. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("release"), gitgraph.WithCommitTag("v1.0.0")).
		Build()

}

Output:
gitGraph
    commit id: "release" tag: "v1.0.0"

func WithCommitType 

func WithCommitType(cType CommitType) CommitOption

WithCommitType sets the commit type.

Example

ExampleWithCommitType changes the shape a commit is drawn as. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitType(gitgraph.CommitTypeHighlight)).
		Build()

}

Output:
gitGraph
    commit type: HIGHLIGHT

type CommitType 

type CommitType string

CommitType is the commit style in git graph.

Example

ExampleCommitType shows the three shapes a commit can be drawn as. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("a"), gitgraph.WithCommitType(gitgraph.CommitTypeNormal)).
		Commit(gitgraph.WithCommitID("b"), gitgraph.WithCommitType(gitgraph.CommitTypeReverse)).
		Commit(gitgraph.WithCommitID("c"), gitgraph.WithCommitType(gitgraph.CommitTypeHighlight)).
		Build()

}

Output:
gitGraph
    commit id: "a" type: NORMAL
    commit id: "b" type: REVERSE
    commit id: "c" type: HIGHLIGHT

const (
	// CommitTypeNormal is default commit style.
	CommitTypeNormal CommitType = "NORMAL"
	// CommitTypeReverse is reverse commit style.
	CommitTypeReverse CommitType = "REVERSE"
	// CommitTypeHighlight is highlight commit style.
	CommitTypeHighlight CommitType = "HIGHLIGHT"
)

type Diagram 

type Diagram struct {
	// contains filtered or unexported fields
}

Diagram is a git graph diagram builder.

Example

ExampleDiagram skips this test on Windows. The newline codes in the comment section where the expected values are written are represented as '\n', causing failures when testing on Windows. 

package main

import (
	"io"
	"os"

	md "github.com/nao1215/markdown"
	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	diagram := gitgraph.NewDiagram(
		io.Discard,
		gitgraph.WithTitle("Release Flow"),
	).
		Commit(gitgraph.WithCommitID("init"), gitgraph.WithCommitTag("v0.1.0")).
		Branch("develop").
		Checkout("develop").
		Commit(gitgraph.WithCommitType(gitgraph.CommitTypeHighlight)).
		Checkout("main").
		Merge("develop", gitgraph.WithCommitTag("v1.0.0")).
		String()

	_ = md.NewMarkdown(os.Stdout).
		H2("Git Graph").
		CodeBlocks(md.SyntaxHighlightMermaid, diagram).
		Build()

}

Output:
## Git Graph
```mermaid
---
title: "Release Flow"
---
gitGraph
    commit id: "init" tag: "v0.1.0"
    branch develop
    checkout develop
    commit type: HIGHLIGHT
    checkout main
    merge develop tag: "v1.0.0"
```
Example (Full)

ExampleDiagram_full shows a git graph built end to end and put into a markdown document, which is what this package exists for. 

package main

import (
	"io"
	"os"

	md "github.com/nao1215/markdown"
	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	diagram := gitgraph.NewDiagram(io.Discard).
		Commit(gitgraph.WithCommitID("initial")).
		String()

	_ = md.NewMarkdown(os.Stdout).
		H2("Diagram").
		CodeBlocks(md.SyntaxHighlightMermaid, diagram).
		Build()

}

Output:
## Diagram
```mermaid
gitGraph
    commit id: "initial"
```

func NewDiagram 

func NewDiagram(w io.Writer, opts ...Option) *Diagram

NewDiagram returns a new Diagram.

Example

ExampleNewDiagram shows the shape every git graph has: a writer, a chain of calls, and Build. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Build()

}

Output:
gitGraph
    commit id: "initial"

func (*Diagram) Branch 

func (d *Diagram) Branch(name string, opts ...BranchOption) *Diagram

Branch adds a branch command to the git graph.

Example

ExampleDiagram_Branch starts a branch and switches to it, so the commits that follow belong to it. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("develop").
		Commit(gitgraph.WithCommitID("work")).
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch develop
    commit id: "work"

func (*Diagram) Build 

func (d *Diagram) Build() error

Build writes the git graph diagram body to the output destination.

Example

ExampleDiagram_Build writes the diagram and reports the first error the chain recorded. Nothing in the chain panics on bad input, so one check at the end is enough. 

package main

import (
	"fmt"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	err := gitgraph.NewDiagram(nil).
		Commit(gitgraph.WithCommitID("initial")).
		Build()
	fmt.Println("error:", err)

}

Output:
error: output writer must not be nil

func (*Diagram) Checkout 

func (d *Diagram) Checkout(name string) *Diagram

Checkout adds a checkout command to the git graph.

Example

ExampleDiagram_Checkout switches back to a branch that already exists. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("develop").
		Commit(gitgraph.WithCommitID("work")).
		Checkout("main").
		Commit(gitgraph.WithCommitID("hotfix")).
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch develop
    commit id: "work"
    checkout main
    commit id: "hotfix"

func (*Diagram) CherryPick 

func (d *Diagram) CherryPick(id string, opts ...CherryPickOption) *Diagram

CherryPick adds a cherry-pick command to the git graph.

Example

ExampleDiagram_CherryPick copies one commit onto the current branch. The commit it names has to exist already. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("develop").
		Commit(gitgraph.WithCommitID("fix")).
		Checkout("main").
		CherryPick("fix").
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch develop
    commit id: "fix"
    checkout main
    cherry-pick id: "fix"

func (*Diagram) Commit 

func (d *Diagram) Commit(opts ...CommitOption) *Diagram

Commit adds a commit command to the git graph.

Example

ExampleDiagram_Commit adds a commit to the current branch. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit().
		Commit(gitgraph.WithCommitID("second")).
		Build()

}

Output:
gitGraph
    commit
    commit id: "second"

func (*Diagram) Error 

func (d *Diagram) Error() error

Error returns the error that occurred during the git graph diagram building.

Example

ExampleDiagram_Error reports the same error Build does, for code that wants to look before writing anything. 

package main

import (
	"fmt"
	"io"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	d := gitgraph.NewDiagram(io.Discard).
		Checkout("never-branched")
	fmt.Println("error:", d.Error())

}

Output:
error: <nil>

func (*Diagram) LF 

func (d *Diagram) LF() *Diagram

LF adds a line feed to the git graph.

Example

ExampleDiagram_LF adds a blank line to the diagram body. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		LF().
		Commit(gitgraph.WithCommitID("initial")).
		Build()

}

Output:
gitGraph
    commit id: "initial"

    commit id: "initial"

func (*Diagram) Merge 

func (d *Diagram) Merge(branch string, opts ...CommitOption) *Diagram

Merge adds a merge command to the git graph.

Example

ExampleDiagram_Merge brings a branch back into the current one. It takes the commit options, because a merge is drawn as a commit and can carry a tag. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Branch("develop").
		Commit(gitgraph.WithCommitID("work")).
		Checkout("main").
		Merge("develop", gitgraph.WithCommitTag("v1.0.0")).
		Build()

}

Output:
gitGraph
    commit id: "initial"
    branch develop
    commit id: "work"
    checkout main
    merge develop tag: "v1.0.0"

func (*Diagram) Reset 

func (d *Diagram) Reset(id string) *Diagram

Reset adds a reset command to the git graph.

Example

ExampleDiagram_Reset moves the current branch back to a commit. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout).
		Commit(gitgraph.WithCommitID("initial")).
		Commit(gitgraph.WithCommitID("mistake")).
		Reset("initial").
		Build()

}

Output:
gitGraph
    commit id: "initial"
    commit id: "mistake"
    reset id: "initial"

func (*Diagram) String 

func (d *Diagram) String() string

String returns the git graph diagram body.

Example

ExampleDiagram_String returns the diagram without needing a writer, which is how it is handed to a markdown code block. 

package main

import (
	"io"
	"os"

	md "github.com/nao1215/markdown"
	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	diagram := gitgraph.NewDiagram(io.Discard).
		Commit(gitgraph.WithCommitID("initial")).
		String()

	_ = md.NewMarkdown(os.Stdout).
		CodeBlocks(md.SyntaxHighlightMermaid, diagram).
		Build()

}

Output:
```mermaid
gitGraph
    commit id: "initial"
```

type Option 

type Option func(*config)

Option sets the options for the Diagram struct.

Example

ExampleOption shows what an Option is: a function that changes how the diagram is written, passed to NewDiagram. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	options := []gitgraph.Option{gitgraph.WithTitle("Overview")}

	_ = gitgraph.NewDiagram(os.Stdout, options...).
		Commit(gitgraph.WithCommitID("initial")).
		Build()

}

Output:
---
title: "Overview"
---
gitGraph
    commit id: "initial"

func WithTitle 

func WithTitle(title string) Option

WithTitle sets the title configuration.

Example

ExampleWithTitle sets the title the diagram is drawn with. 

package main

import (
	"os"

	"github.com/nao1215/markdown/mermaid/gitgraph"
)

func main() {
	_ = gitgraph.NewDiagram(os.Stdout, gitgraph.WithTitle("Overview")).
		Commit(gitgraph.WithCommitID("initial")).
		Build()

}

Output:
---
title: "Overview"
---
gitGraph
    commit id: "initial"

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.