---
title: "Printing directory trees with printtree"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Printing directory trees with printtree}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(printtree)
```

## Basic Usage

Print the tree for current working directory

```{r}
tmp <- tempdir()
demo <- file.path(tmp, "printtree-demo")

# Start fresh

if (dir.exists(demo)) unlink(demo, recursive = TRUE, force = TRUE)

dir.create(demo, recursive = TRUE)
dir.create(file.path(demo, "R"))
dir.create(file.path(demo, "data", "raw"), recursive = TRUE)

file.create(file.path(demo, "R", "hello.R"))
file.create(file.path(demo, "README.md"))
file.create(file.path(demo, ".Rhistory"))

```

Print the tree

```{r}
print_rtree()
```

## Project root detection

When project = "root", printtree can walk upward from the provided path to detect a project root using simple markers. By default this includes:

-   .Rproj files (RStudio / Posit projects)

-   DESCRIPTION files (R package roots)

In this example, we mark demo as a package-like root by creating a DESCRIPTION file, then print from a subdirectory:

```{r}
file.create(file.path(demo, "DESCRIPTION"))
subdir <- file.path(demo, "data", "raw")
print_rtree(subdir, project = "root")
```

You can customize detection using rootmarkers:

```{r}
print_rtree(subdir,
project = "root",
root_markers = c(".Rproj", "DESCRIPTION", "_quarto.yml"))

```

## Common Options

Limit depth:

```{r}
print_rtree(max_depth = 2)

```

By default, output ends with a count summary for the displayed tree:

```{r}
print_rtree(demo, max_depth = 1)
```

Suppress the footer when you want the older compact output:

```{r}
print_rtree(demo, max_depth = 1, count_footer = FALSE)
```

Ignore exact names or patterns. With the default `ignore_type = "auto"`, wildcard values are treated as glob patterns:

```{r}
file.create(file.path(demo, "debug.log"))
print_rtree(demo, ignore = c("*.log", ".Rhistory"), max_depth = 2)
```

Use regular expressions when you need them:

```{r}
print_rtree(demo, ignore = "^README", ignore_type = "regex", max_depth = 1)
```

Prune directories that have no displayable children:

```{r}
dir.create(file.path(demo, "logs"))
file.create(file.path(demo, "logs", "debug.log"))
print_rtree(demo, ignore = "*.log", prune = TRUE)
```

Show hidden files:

```{r}
print_rtree(demo, show_hidden = TRUE, max_depth = 2)

```

Use unicode tree glyphs (if your terminal supports them):

```{r}
print_rtree(demo, format = "unicode", max_depth = 2)

```

Annotate files with Git status when the tree is inside a Git work tree:

```{r, eval = FALSE}
print_rtree(git = TRUE)
```

Use `quiet = TRUE` when you want to capture lines without printing:

```{r}
lines <- print_rtree(demo, return_lines = TRUE, quiet = TRUE)
head(lines)
```

Write a tree to a text or Markdown file:

```{r}
tree_md <- file.path(tempdir(), "printtree-output", "tree.md")
write_tree(demo, tree_md, format = "md", title = "Demo Tree")
```

Generate a PNG snapshot:

```{r}
# Save PNG snapshots 
png_light <- tempfile("tree-light-", fileext = ".png")
png_dark  <- tempfile("tree-dark-",  fileext = ".png")

# Light (white bg, black text)
print_rtree(demo, snapshot = TRUE, snapshot_bg = "white", snapshot_file = png_light)

# Dark (black bg, white text)
print_rtree(demo, snapshot = TRUE, snapshot_bg = "black", snapshot_file = png_dark)


```