Package 'printtree'

Title: Print Directory Trees for R Projects and Folders
Description: Quickly visualize 'R' project directory structures with automatic project detection and clean tree output.
Authors: George Arthur [aut, cre, cph]
Maintainer: George Arthur <[email protected]>
License: MIT + file LICENSE
Version: 0.3.0
Built: 2026-10-12 23:23:10 UTC
Source: https://github.com/prigasg/printtree

Help Index


Diff Two Directory Trees as a Graphviz DOT Graph

Description

Builds both trees with the same options and renders the difference as a Graphviz DOT graph: nodes only in after are filled green, nodes only in before are filled red and dashed, and unchanged nodes are neutral. Nodes are matched by their path relative to each tree root.

Usage

tree_diff_dot(
  before,
  after,
  rankdir = c("TB", "LR", "RL", "BT"),
  file = NULL,
  ...
)

Arguments

before

Character. Directory path for the "before" tree.

after

Character. Directory path for the "after" tree.

rankdir

Character. Graph direction: "TB" (top-bottom), "LR" (left-right), "RL", or "BT".

file

Character or NULL. If given, the diagram text is written to this file with writeLines().

...

Additional arguments passed to build_tree() for both trees (e.g. ignore, max_depth, show_hidden, prune).

Value

Invisibly, the diagram text as a single string (or file when file is given).

Examples

old <- file.path(tempdir(), "printtree-diff-old")
new <- file.path(tempdir(), "printtree-diff-new")
for (d in c(old, new)) {
  if (dir.exists(d)) unlink(d, recursive = TRUE)
  dir.create(d, recursive = TRUE)
}
file.create(file.path(old, "gone.txt"))
file.create(file.path(new, "added.txt"))

cat(tree_diff_dot(old, new))

# Left-to-right layout
cat(tree_diff_dot(old, new, rankdir = "LR"))

Diff Two Directory Trees as a Mermaid Flowchart

Description

Builds both trees with the same options and renders the difference as a Mermaid flowchart: nodes only in after are green, nodes only in before are red and dashed, and unchanged nodes are neutral. Nodes are matched by their path relative to each tree root.

Usage

tree_diff_mermaid(
  before,
  after,
  direction = c("TD", "LR", "RL", "BT"),
  file = NULL,
  ...
)

Arguments

before

Character. Directory path for the "before" tree.

after

Character. Directory path for the "after" tree.

direction

Character. Flowchart direction: "TD" (top-down), "LR" (left-right), "RL", or "BT".

file

Character or NULL. If given, the diagram text is written to this file with writeLines().

...

Additional arguments passed to build_tree() for both trees (e.g. ignore, max_depth, show_hidden, prune).

Value

Invisibly, the diagram text as a single string (or file when file is given).

Examples

old <- file.path(tempdir(), "printtree-diff-old")
new <- file.path(tempdir(), "printtree-diff-new")
for (d in c(old, new)) {
  if (dir.exists(d)) unlink(d, recursive = TRUE)
  dir.create(d, recursive = TRUE)
}
file.create(file.path(old, "gone.txt"))
file.create(file.path(new, "added.txt"))
file.create(file.path(old, "kept.txt"))
file.create(file.path(new, "kept.txt"))

cat(tree_diff_mermaid(old, new))

# Left-to-right layout
cat(tree_diff_mermaid(old, new, direction = "LR"))

Convert a Directory Tree to a Graphviz DOT Graph

Description

Builds the directory tree with the same options as build_tree() and returns it as Graphviz DOT text. The output renders in Quarto documents (in a {dot} chunk when Graphviz is installed) and with any DOT-compatible tool. Directories use the folder shape and files use the note shape.

Usage

tree_to_dot(
  path = NULL,
  rankdir = c("TB", "LR", "RL", "BT"),
  file = NULL,
  git_colors = FALSE,
  repo_url = NULL,
  repo_branch = "main",
  ...
)

Arguments

path

Character. Directory path, project name, or .Rproj file. If NULL, uses the current directory.

rankdir

Character. Graph direction: "TB" (top-bottom), "LR" (left-right), "RL", or "BT".

file

Character or NULL. If given, the diagram text is written to this file with writeLines().

git_colors

Logical. If TRUE, nodes are filled by their Git status (amber for modified, green for untracked, blue for staged). Implies git = TRUE unless git is set explicitly.

repo_url

Character or NULL. Base URL of the Git repository, e.g. "https://github.com/user/repo". If given, every node gets a URL attribute linking to the file (blob) or directory (tree) on repo_branch, so SVG output is clickable.

repo_branch

Character. Branch used to build the repo_url links.

...

Additional arguments passed to build_tree() (e.g. ignore, max_depth, show_hidden, prune).

Value

Invisibly, the diagram text as a single string (or file when file is given). Use cat() to print it.

Examples

demo <- file.path(tempdir(), "printtree-dot-demo")
if (dir.exists(demo)) unlink(demo, recursive = TRUE)
dir.create(file.path(demo, "R"), recursive = TRUE)
file.create(file.path(demo, "R", "hello.R"))
file.create(file.path(demo, "README.md"))

cat(tree_to_dot(demo))

# Left-to-right layout with clickable nodes
cat(tree_to_dot(demo, rankdir = "LR",
                repo_url = "https://github.com/PrigasG/printtree"))

Convert a Directory Tree to a Collapsible HTML Page

Description

Builds the directory tree with the same options as build_tree() and returns it as a self-contained HTML document: directories expand and collapse on click, with no external dependencies. When the tree is built with git = TRUE, Git status badges are shown next to changed entries.

Usage

tree_to_html(path = NULL, title = NULL, file = NULL, git_colors = FALSE, ...)

Arguments

path

Character. Directory path, project name, or .Rproj file. If NULL, uses the current directory.

title

Character or NULL. Page title and heading. Defaults to "Directory tree".

file

Character or NULL. If given, the HTML is written to this file with writeLines().

git_colors

Logical. If TRUE, nodes are colored by their Git status (badges for modified, untracked, and staged files). Implies git = TRUE.

...

Additional arguments passed to build_tree() (e.g. ignore, max_depth, show_hidden, prune, git).

Value

Invisibly, the HTML document as a single string (or file when file is given).

Examples

demo <- file.path(tempdir(), "printtree-html-demo")
if (dir.exists(demo)) unlink(demo, recursive = TRUE)
dir.create(file.path(demo, "R"), recursive = TRUE)
file.create(file.path(demo, "R", "hello.R"))

html <- tree_to_html(demo, title = "Demo project")
out <- tempfile(fileext = ".html")
tree_to_html(demo, file = out)

# Inside a Git checkout, git_colors = TRUE adds status badges
# next to modified, untracked, and staged files

Convert a Directory Tree to a Mermaid Flowchart

Description

Builds the directory tree with the same options as build_tree() and returns it as Mermaid flowchart text. The output renders natively in Quarto documents (in a {mermaid} chunk), GitHub Markdown, and anywhere else Mermaid is supported. Directories use the stadium shape and files use rectangles.

Usage

tree_to_mermaid(
  path = NULL,
  direction = c("TD", "LR", "RL", "BT"),
  file = NULL,
  git_colors = FALSE,
  subgraph = FALSE,
  repo_url = NULL,
  repo_branch = "main",
  ...
)

Arguments

path

Character. Directory path, project name, or .Rproj file. If NULL, uses the current directory.

direction

Character. Flowchart direction: "TD" (top-down), "LR" (left-right), "RL", or "BT".

file

Character or NULL. If given, the diagram text is written to this file with writeLines().

git_colors

Logical. If TRUE, nodes are colored by their Git status (amber for modified, green for untracked, blue for staged). Implies git = TRUE unless git is set explicitly.

subgraph

Logical. If TRUE, each directory is wrapped in a Mermaid subgraph block so directories render as visual containers.

repo_url

Character or NULL. Base URL of the Git repository, e.g. "https://github.com/user/repo". If given, every node becomes clickable and links to the file (blob) or directory (tree) on repo_branch.

repo_branch

Character. Branch used to build the repo_url links.

...

Additional arguments passed to build_tree() (e.g. ignore, max_depth, show_hidden, prune).

Value

Invisibly, the diagram text as a single string (or file when file is given). Use cat() to print it, e.g. into a Quarto {mermaid} chunk.

Examples

demo <- file.path(tempdir(), "printtree-mermaid-demo")
if (dir.exists(demo)) unlink(demo, recursive = TRUE)
dir.create(file.path(demo, "R"), recursive = TRUE)
file.create(file.path(demo, "R", "hello.R"))
file.create(file.path(demo, "README.md"))

cat(tree_to_mermaid(demo))

# Directories as visual containers, laid out left to right
cat(tree_to_mermaid(demo, subgraph = TRUE, direction = "LR"))

# Nodes that link into the repository on GitHub
cat(tree_to_mermaid(demo,
                    repo_url = "https://github.com/PrigasG/printtree"))

Convert a Directory Tree to a Mermaid Mindmap

Description

Builds the directory tree with the same options as build_tree() and returns it as Mermaid mindmap text: a radial alternative to the flowchart produced by tree_to_mermaid(). The root uses the cloud shape and every level is indented beneath its parent.

Usage

tree_to_mindmap(path = NULL, file = NULL, ...)

Arguments

path

Character. Directory path, project name, or .Rproj file. If NULL, uses the current directory.

file

Character or NULL. If given, the diagram text is written to this file with writeLines().

...

Additional arguments passed to build_tree() (e.g. ignore, max_depth, show_hidden, prune).

Value

Invisibly, the diagram text as a single string (or file when file is given). Use cat() to print it, e.g. into a Quarto {mermaid} chunk.

Examples

demo <- file.path(tempdir(), "printtree-mindmap-demo")
if (dir.exists(demo)) unlink(demo, recursive = TRUE)
dir.create(file.path(demo, "R"), recursive = TRUE)
file.create(file.path(demo, "R", "hello.R"))

cat(tree_to_mindmap(demo))

# Save a mindmap file, ready for a Quarto {mermaid} chunk
tree_to_mindmap(demo, file = tempfile(fileext = ".mmd"))

Preview a Directory Tree as a Mermaid Diagram

Description

Writes an HTML page that renders tree_to_mermaid() output as an SVG diagram in a web browser. The page loads Mermaid from its public CDN, so rendering requires an internet connection. Browser opening is always suppressed in non-interactive sessions, including package checks and automated jobs.

Usage

view_mermaid(
  path = NULL,
  file = tempfile("printtree-mermaid-", fileext = ".html"),
  title = "Directory tree",
  theme = c("default", "neutral", "dark", "forest", "base"),
  open = interactive(),
  pan_zoom = TRUE,
  save = NULL,
  ...
)

Arguments

path

Character. Directory path, project name, or .Rproj file. If NULL, uses the current directory.

file

Character. HTML output path. By default, a temporary file is used.

title

Character. Page title and heading.

theme

Mermaid theme: "default", "neutral", "dark", "forest", or "base".

open

Logical. Open the generated page when running interactively. Browser opening is skipped when interactive() is false, even if this is explicitly set to TRUE.

pan_zoom

Logical. Enable pan/zoom controls for navigating large diagrams (via the svg-pan-zoom library).

save

Character or NULL. If given, render the diagram to an image file instead of the HTML page: one of "png", "jpeg" (or "jpg"), or "pdf". Requires the webshot2 package and a Chrome/Chromium browser. When save is given, file is treated as the image output path; if file was not explicitly supplied, the path is derived from title and the save extension. A missing extension is appended; a conflicting extension is an error. PNG/JPEG capture only the diagram element; PDF uses print CSS to hide the viewer UI.

...

Additional arguments passed to tree_to_mermaid(), such as direction, ignore, max_depth, git_colors, or subgraph.

Value

Invisibly, the generated HTML file path (or the image path when save is given).

Examples

demo <- file.path(tempdir(), "printtree-view-demo")
if (dir.exists(demo)) unlink(demo, recursive = TRUE)
dir.create(file.path(demo, "R"), recursive = TRUE)
file.create(file.path(demo, "R", "hello.R"))
file.create(file.path(demo, "README.md"))

preview <- view_mermaid(demo, open = FALSE)
file.exists(preview)

Write a Directory Tree to a Text, Markdown, Diagram, or Quarto File

Description

Builds a directory tree with the same options as print_rtree() and writes it to a plain text, Markdown, diagram, or Quarto file.

Usage

write_tree(
  path = NULL,
  file,
  format = c("txt", "md", "mermaid", "dot", "qmd", "mindmap", "html"),
  title = NULL,
  create_dirs = TRUE,
  ...
)

Arguments

path

Character. Directory path, project name, or .Rproj file. If NULL, uses current directory.

file

Character. Output file path.

format

One of "txt", "md", "mermaid", "dot", "qmd", "mindmap", or "html". "mermaid" writes a Mermaid flowchart (renders in Quarto {mermaid} chunks and GitHub Markdown), "dot" writes a Graphviz DOT graph, "qmd" writes a minimal Quarto document embedding the Mermaid flowchart, "mindmap" writes a Mermaid mindmap, and "html" writes a self-contained collapsible HTML tree.

title

Optional heading: used as the Markdown heading when format = "md", as the Quarto document title when format = "qmd", and as the page title and heading when format = "html".

create_dirs

Logical. If TRUE, create the output file's parent directory when it does not exist.

...

Additional arguments passed to the underlying tree builder (the same tree options as print_rtree(), such as ignore, max_depth, git, or prune). Diagram engines also accept direction (Mermaid), rankdir (DOT), git_colors, subgraph, and repo_url/repo_branch; see tree_to_mermaid() and tree_to_dot().

Value

Invisibly returns the output file path.

Examples

demo <- file.path(tempdir(), "printtree-write-demo")
if (dir.exists(demo)) unlink(demo, recursive = TRUE)
dir.create(demo, recursive = TRUE)
file.create(file.path(demo, "README.md"))

out <- tempfile(fileext = ".md")
write_tree(demo, out, format = "md")

# Mermaid flowchart and a Quarto document embedding it
write_tree(demo, tempfile(fileext = ".mmd"), format = "mermaid")
write_tree(demo, tempfile(fileext = ".qmd"), format = "qmd",
           title = "Demo project tree")

# Mermaid mindmap and a collapsible HTML tree
write_tree(demo, tempfile(fileext = ".mmd"), format = "mindmap")
write_tree(demo, tempfile(fileext = ".html"), format = "html",
           title = "Demo project tree")