gtree
Provide CLI, Package and Web for tree output and directories creation from Markdown or programmatically
About gtree
This large README is shown as a plain-text preview. Read the full README at the source
<img src="assets/heart-balloon.svg" width="77">[^1]<br>
[](https://github.com/ddddddO/gtree/releases)</br>
[](https://deepwiki.com/ddddddO/gtree)<br>
[](https://pkg.go.dev/github.com/ddddddO/gtree) [](https://codecov.io/gh/ddddddO/gtree) [](https://github.com/ddddddO/gtree/actions/workflows/ci.yaml)</br>
[](https://github.com/avelino/awesome-go#uncategorized) [](https://ddddddo.github.io/gtree/) [](https://github.com/ddddddO/gtree/blob/master/LICENSE)
Easily output ASCII tree from Go program or Markdown unordered list (and it does more than just output tree!🌳🗂🔍)
There's also a CLI tool that can output a tree from JSON, YAML, or TOML! It's called *xtree*.
# Table of Contents
- Features
- Package - **[Programmable tree structure](https://github.com/ddddddO/gtree?#package---programmable-tree-structure)**
- Recommended for developers!👍
- **[Acknowledgments](https://github.com/ddddddO/gtree?#acknowledgments)**
- Package - **[Markdown to tree structure](https://github.com/ddddddO/gtree?#package---markdown-to-tree-structure)**
- **[Web](https://github.com/ddddddO/gtree?#web)**
- Generate ASCII tree from unordered Markdown list in Web UI (with editable branches).
- CLI - **[gtree](https://github.com/ddddddO/gtree?#gtree)**
- Generate ASCII tree or directory from Markdown unordered list.
- CLI - **[xtree](https://github.com/ddddddO/gtree?#xtree)**
- Generate ASCII tree from JSON/YAML/TOML.
- [Documents](https://github.com/ddddddO/gtree?#documents)
- [Process](https://github.com/ddddddO/gtree?#process)
- [Performance](https://github.com/ddddddO/gtree?#performance)
- [Contributing](https://github.com/ddddddO/gtree?#contributing)
- [Test coverage](https://github.com/ddddddO/gtree?#test-coverage)
# Package - Programmable tree structure
> [!NOTE]
> There are sample repositories that use gtree package.<br>
> See [here](https://github.com/ddddddO/gtree/blob/master/example/README.md) for details.
## Simple example
I urge you to run this program. This package is probably the easiest Go package to output tree.
```go
package main
import (
"fmt"
"os"
"github.com/ddddddO/gtree"
)
func main() {
var root *gtree.Node = gtree.NewRoot("root")
root.Add("child 1").Add("child 2").Add("child 3")
var child4 *gtree.Node = root.Add("child 1").Add("child 2").Add("child 4")
child4.Add("child 5")
child4.Add("child 6").Add("child 7")
root.Add("child 8")
if err := gtree.OutputFromRoot(os.Stdout, root); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
// Output:
// root
// ├── child 1
// │ └── child 2
// │ ├── child 3
// │ └── child 4
// │ ├── child 5
// │ └── child 6
// │ └── child 7
// └── child 8
}
```
## Installation
Go version requires 1.24 or later.
```console
$ go get github.com/ddddddO/gtree
```
## Usage
|Function|Description|Available optional functions|
|--|--|--|
|*[OutputFromRoot](https://pkg.go.dev/github.com/ddddddO/gtree#OutputFromRoot)*|can output tree|WithMidBranch<br>WithLastBranch<br>WithVLine<br>WithHLine<br>WithEncodeJSON<br>WithEncodeTOML<br>WithEncodeYAML|
|*[MkdirFromRoot](https://pkg.go.dev/github.com/ddddddO/gtree#MkdirFromRoot)*|can create directories|WithTargetDir<br>WithFileExtensions<br>WithDryRun|
|*[VerifyFromRoot](https://pkg.go.dev/github.com/ddddddO/gtree#VerifyFromRoot)*|can output the difference between tree you composed and directories|WithTargetDir<br>WithStrictVerify|
|*[WalkFromRoot](https://pkg.go.dev/github.com/ddddddO/gtree#WalkFromRoot)*|can execute user-defined function while traversing tree structure recursively|WithMidBranch<br>WithLastBranch<br>WithVLine<br>WithHLine|
|*[WalkIterFromRoot](https://pkg.go.dev/github.com/ddddddO/gtree#WalkIterFromRoot)*|it returns each node resulting from a recursive traversal of the tree structure, so you can process on each node|WithMidBranch<br>WithLastBranch<br>WithVLine<br>WithHLine|
> [!TIP]
> Specifying ***WithDuplicationAllowed*** function in ***NewRoot*** function,
> which generates the Node arguments for the above functions,
> allows multiple nodes with the same text to exist within the same hierarchy.
### Standard Pattern and Pattern Allowing Node Duplication
```go
package main
import (
"os"
"github.com/ddddddO/gtree"
)
func main() {
rootOfStandard := gtree.NewRoot("Standard Pattern")
addChildren(rootOfStandard)
_ = gtree.OutputFromRoot(os.Stdout, rootOfStandard)
// Standard Pattern
// ├── child 1
// │ └── child 2
// │ ├── child 3
// │ └── child 4
// │ ├── child 5
// │ └── child 6
// │ ├── child 7
// │ └── child 9
// └── child 8
rootOfAllowedDuplication := gtree.NewRoot("Pattern Allowing Node Duplication", gtree.WithDuplicationAllowed())
addChildren(rootOfAllowedDuplication)
_ = gtree.OutputFromRoot(os.Stdout, rootOfAllowedDuplication)
// Pattern Allowing Node Duplication
// ├── child 1
// │ └── child 2
// │ └── child 3
// ├── child 1
// │ └── child 2
// │ └── child 4
// │ ├── child 5
// │ ├── child 6
// │ │ └── child 7
// │ ├── child 6
// │ │ └── child 9
// │ └── child 5
// └── child 8
}
func addChildren(root *gtree.Node) {
root.Add("child 1").Add("child 2").Add("child 3")
var child4 *gtree.Node = root.Add("child 1").Add("child 2").Add("child 4")
child4.Add("child 5")
child4.Add("child 6").Add("child 7")
child4.Add("child 6").Add("child 9")
child4.Add("child 5")
root.Add("child 8")
}
```
## Acknowledgments
### Thanks for providing very useful CLI for cloud storage tree output🤩🎉
Everyone is encouraged to use them!
#### ⭐[_orangekame3/stree_](https://github.com/orangekame3/stree)
CLI for **Amazon S3** tree output.</br>
[_aws s3_](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/index.html) command does not do what `tree` command does, but [**_stree_**](https://github.com/orangekame3/stree) command can display tree!
#### ⭐[_owlinux1000/gcstree_](https://github.com/owlinux1000/gcstree)
CLI for **Google Cloud Storage** tree output.</br>
[_gcloud storage_](https://cloud.google.com/sdk/gcloud/reference/storage) command does not do what `tree` command does, but [**_gcstree_**](https://github.com/owlinux1000/gcstree) command can display tree!
### gtree packeage has been utilized for other tools as well🚀
I hope you will use these tools as well!
- [Tools](https://github.com/ddddddO/gtree/network/dependents)
# Package - Markdown to tree structure
## Installation
Go version requires 1.24 or later.
```console
$ go get github.com/ddddddO/gtree
```
## Usage
The symbols that can be used in Markdown are `*`, `-`, `+`, and `#`.
|Function|Description|Available optional functions|
|--|--|--|
|*[OutputFromMarkdown](https://pkg.go.dev/github.com/ddddddO/gtree#OutputFromMarkdown)*|can output trees|WithMidBranch<br>WithLastBranch<br>WithVLine<br>WithHLine<br>WithEncodeJSON<br>WithEncodeTOML<br>WithEncodeYAML<br>WithMassive|
|*[MkdirFromMarkdown](https://pkg.go.dev/github.com/ddddddO/gtree#MkdirFromMarkdown)*|can create directories|WithTargetDir<br>WithFileExtensions<br>WithDryRun<br>WithMassive|
|*[VerifyFromMarkdown](https://pkg.go.dev/github.com/ddddddO/gtree#VerifyFromMarkdown)*|can output the difference between markdown and directories|WithTargetDir<br>WithStrictVerify<br>WithMassive|
|*[WalkFromMarkdown](https://pkg.go.dev/github.com/ddddddO/gtree#WalkFromMarkdown)*|can execute user-defined function while traversing tree structure recursively|WithMidBranch<br>WithLastBranch<br>WithVLine<br>WithHLine<br>WithMassive|
# Web
https://ddddddo.github.io/gtree/
This page is that converts from Markdown to tree!<br>
This page calls a function that outputs tree. This function is a Go package compiled as WebAssembly.<br>
The symbols that can be used in Markdown are `*`, `-`, `+`, and `#`.<br>
Indentation represents hierarchy. The indentation can be whatever you specify, but use the same pattern.<br>
You can change the branches like in the image below.<br>
Also, once loaded, you can enjoy offline!<br>
You can open it in your browser with
```console
$ gtree web
```
[source code](cmd/gtree-wasm/)
# CLI
## *gtree*
<img src="assets/demo.gif"><br>
### Installation
<pre>
<b>Go</b>
$ go install github.com/ddddddO/gtree/cmd/gtree@latest
<a href="https://github.com/aquaproj/aqua-registry/blob/main/pkgs/ddddddO/gtree/pkg.yaml"><b>aqua</b></a>
$ aqua g -i ddddddO/gtree
<a href="https://github.com/Homebrew/homebrew-core/blob/master/Formula/g/gtree.rb"><b>Homebrew</b></a>
$ brew install gtree
<a href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/gt/gtree/package.nix"><b>Nix</b></a>
$ nix-env -i gtree
or
$ nix-shell -p gtree
<a href="https://github.com/macports/macports-ports/blob/master/sysutils/gtree/Portfile"><b>MacPorts</b></a>
$ port install gtree
<s><a href="https://aur.archlinux.org/packages/gtree"><b>AUR</b></a></s>
$ wip...
<b>Scoop</b>
$ scoop bucket add ddddddO https://github.com/ddddddO/scoop-bucket.git
$ scoop install ddddddO/gtree
<b>deb</b>
$ export GTREE_VERSION=X.X.X
$ curl -o gtree.deb -L https://github.com/ddddddO/gtree/releases/download/v$GTREE_VERSION/gtree_$GTREE_VERSION-1_amd64.deb
$ dpkg -i gtree.deb
<b>rpm</b>
$ export GTREE_VERSION=X.X.X
$ yum install https://github.com/ddddddO/gtree/releases/download/v$GTREE_VERSION/gtree_$GTREE_VERSION-1_amd64.rpm
<b>apk</b>
$ export GTREE_VERSION=X.X.X
$ curl -o gtree.apk -L https://github.com/ddddddO/gtree/releases/download/v$GTREE_VERSION/gtree_$GTREE_VERSION-1_amd64.apk
$ apk add --allow-untrusted gtree.apk
<a href="https://github.com/ddddddO/gtree/pkgs/container/gtree"><b>Docker</b></a>
$ docker pull ghcr.io/ddddddo/gtree:latest
$ docker run ghcr.io/ddddddo/gtree:latest template | docker run -i ghcr.io/ddddddo/gtree:latest output
gtree
├── cmd
│ └── gtree
│ └── main.go
├── testdata
│ ├── sample1.md
│ └── sample2.md
├── Makefile
└── tree.go
</pre>
#### etc
**download binary from [here](https://github.com/ddddddO/gtree/releases).**
### Usage
```console
$ gtree --help
NAME:
gtree - This CLI uses Markdown to generate directory trees and directories itself, and also verifies directories.
The symbols that can be used in Markdown are '-', '+', '*', and '#'.
Within Markdown, indentation represents hierarchy. The indentation can be whatever you specify, but use the same pattern.
USAGE:
gtree [global options] command [command options] [arguments...]
VERSION:
1.10.2 / revision 85520a1
COMMANDS:
output, o, out Outputs tree from markdown.
Let's try 'gtree template | gtree output'.
mkdir, m Makes directories and files from markdown. It is possible to dry run.
Let's try 'gtree template | gtree mkdir -e .go -e .md -e Makefile'.
verify, vf Verifies tree structure represented in markdown by comparing it with existing directories.
Let's try 'gtree template | gtree verify'.
template, t, tmpl Outputs markdown template. Use it to try out gtree CLI.
web, w, www Opens "Tree Maker" in your browser and shows the URL in terminal.
version, v Prints the version.
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--help, -h show help
--version, -v print the version
```
#### *Output* subcommand
```console
$ gtree output --help
NAME:
gtree output - Outputs tree from markdown.
Let's try 'gtree template | gtree output'.
USAGE:
gtree output [command options] [arguments...]
OPTIONS:
--file value, -f value specify the path to markdown file. (default: stdin)
--massive, -m set this option when there are very many blocks of markdown. (default: false)
--massive-timeout value, --mt value set this option if you want to set a timeout. (default: 0s)
--format value set this option when specifying output format. "json", "yaml", "toml"
--watch, -w follow changes in markdown file. (default: false)
--help, -h show help
```
##### Try it!
```console
$ gtree template
- gtree
- cmd
- gtree
- main.go
- testdata
- sample1.md
- sample2.md
- Makefile
- tree.go
$ gtree template | gtree output
gtree
├── cmd
│ └── gtree
│ └── main.go
├── testdata
│ ├── sample1.md
│ └── sample2.md
├── Makefile
└── tree.go
```
Other pattern.
```
├── gtree output -f testdata/sample1.md
├── cat testdata/sample1.md | gtree output -f -
└── cat testdata/sample1.md | gtree output
```
##### Usage other than representing a directory.
```console
$ cat testdata/sample2.md | gtree output
k8s_resources
├── (Tier3)
│ └── (Tier2)
│ └── (Tier1)
│ └── (Tier0)
├── Deployment
│ └── ReplicaSet
│ └── Pod
│ └── container(s)
├── CronJob
│ └── Job
│ └── Pod
│ └── container(s)
└── (empty)
├── DaemonSet
│ └── Pod
│ └── container(s)
└── StatefulSet
└── Pod
└── container(s)
```
##### Multiple roots
```console
$ cat testdata/sample6.md | gtree output
Artiodactyla
├── Artiofabula
│ ├── Cetruminantia
│ │ ├── Whippomorpha
│ │ │ ├── Hippopotamidae
│ │ │ └── Cetacea
│ │ └── Ruminantia
│ └── Suina
└── Tylopoda
Carnivora
├── Feliformia
└── Caniformia
├── Canidae
└── Arctoidea
├── Ursidae
└── x
├── Pinnipedia
└── Musteloidea
├── Ailuridae
└── x
├── Mephitidae
└── x
├── Procyonidae
└── Mustelidae
```
##### Output JSON
<details><summary>see</summary>
```console
$ cat testdata/sample5.md | gtree output --format json | jq
{
"value": "a",
"children": [
{
"value": "i",
"children": [
{
"value": "u",
"children": [
{
"value": "k",
"children": null
},
{
"value": "kk",
"children": null
}
]
},
{
"value": "t",
"children": null
}
]
},
{
"value": "e",
"children": [
{
"value": "o",
"children": null
}
]
},
{
"value": "g",
"children": null
}
]
}
```
</details>
##### Output YAML
<details><summary>see</summary>
```console
$ cat testdata/sample5.md | gtree output --format yaml
value: a
children:
- value: i
children:
- value: u
children:
- value: k
children: []
- value: kk
children: []
- value: t
children: []
- value: e
children:
- value: o
children: []
- value: g
children: []
```
</details>
##### Output TOML
<details><summary>see</summary>
```console
$ cat testdata/sample5.md | gtree output --format toml
value = 'a'
[[children]]
value = 'i'
[[children.children]]
value = 'u'
[[children.children.children]]
value = 'k'
children = []
[[children.children.children]]
value = 'kk'
children = []
[[children.children]]
value = 't'
children = []
[[children]]
value = 'e'
[[children.children]]
value = 'o'
children = []
[[children]]
value = 'g'
children = []
```
</details>
#### *Mkdir* subcommand
```console
$ gtree mkdir --help
NAME:
gtree mkdir - Makes directories and files from markdown. It is possible to dry run.
Let's try 'gtree template | gtree mkdir -e .go -e .md -e Makefile'.
USAGE:
gtree mkdir [command options] [arguments...]
OPTIONS:
--file value, -f value specify the path to markdown file. (default: stdin)
--dry-run, -d dry run. detects node that is invalid for directory generation. the order of the output and made directories does not always match. (default: false)
--extension value, -e value [ --extension value, -e value ] set this option if you want to create file instead of directory. for example, if you want to generate files with ".go" extension: "-e .go"
--target-dir value set this option if you want to specify the directory you want to make directory. (default: current directory)
--help, -h show help
```
##### Try it!
```console
$ gtree template
- gtree
- cmd
- gtree
- main.go
- testdata
- sample1.md
- sample2.md
- Makefile
- tree.go
$ gtree template | gtree mkdir
$ tree gtree/
gtree/
├── cmd
│ └── gtree
│ └── main.go
├── Makefile
├── testdata
│ ├── sample1.md
│ └── sample2.md
└── tree.go
8 directories, 0 files
```
##### *make directories and files*
```console
$ gtree template
- gtree
- cmd
- gtree
- main.go
- testdata
- sample1.md
- sample2.md
- Makefile
- tree.go
$ gtree template | gtree mkdir -e .go -e .md -e Makefile
$ tree gtree/
gtree/
├── cmd
│ └── gtree
│ └── main.go
├── Makefile
├── testdata
│ ├── sample1.md
│ └── sample2.md
└── tree.go
3 directories, 5 files
```
##### *dry run*
Does not create a file and directory.
```console
$ gtree template | gtree mkdir --dry-run -e .go -e .md -e Makefile
gtree
├── cmd
│ └── gtree
│ └── main.go
├── testdata
│ ├── sample1.md
│ └── sample2.md
├── Makefile
└── tree.go
4 directories, 5 files
```
Any invalid file or directory name will result in an error.
```console
$ gtree mkdir --dry-run <<EOS
- root
- aa
- bb
- b/b
EOS
invalid node value: b/b
```
```console
$ gtree mkdir --dry-run <<EOS
- /root
- aa
- bb
- bbFrequently Asked Questions
What is gtree?
gtree is a Miscellaneous library for the Go programming language. Provide CLI, Package and Web for tree output and directories creation from Markdown or programmatically
How do I install gtree?
Install gtree with the Go module system using `go get ddddddO/gtree`. Check the repository for the current installation instructions.
What category does gtree belong to?
gtree is listed under Miscellaneous, specifically Uncategorized.