Package {tinytrail}

Title: Lightweight Auto-Updating Project Tracker and Data Dictionary
Version: 0.1.0
Description: Once initialized, the package leaves a 'tiny trail' of human- and AI-readable text that makes it effortless to keep track of small to medium-sized projects. The package is lightweight (hence 'tiny') and maintains a YAML trail file recording which scripts produced which output files. Call tinytrail() once at the top of each script to record metadata, wrap any save call with tinytrail_write() to log the output path, and optionally use tinytrail_dict() to capture a data dictionary for each input data frame.
License: MIT + file LICENSE
Depends: R (≥ 4.1.0)
Imports: yaml
Encoding: UTF-8
Language: en-US
RoxygenNote: 8.0.0
URL: https://github.com/tinytrail-r/tinytrail, https://tinytrail-r.github.io/tinytrail/
BugReports: https://github.com/tinytrail-r/tinytrail/issues
Suggests: arrow, data.table, ggplot2, haven, jsonlite, kableExtra, knitr, openxlsx, purrr, readr, rmarkdown, rstudioapi, testthat (≥ 3.0.0), tinytable, withr, writexl
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-06-30 06:26:03 UTC; tomas
Author: Tomas Reivinger [aut, cre, cph]
Maintainer: Tomas Reivinger <tomas.reivinger@gmail.com>
Repository: CRAN
Date/Publication: 2026-07-04 08:40:02 UTC

Register a script in the project trail

Description

Call once near the top of every script. Creates or updates an entry in ⁠_tinytrail.yaml⁠ and sets the script name so that outputs can be recorded.

Usage

tinytrail(
  description,
  data_source = NULL,
  pin_to_top = FALSE,
  record_runtime = TRUE,
  name = NULL,
  auto = TRUE,
  extra_hooks = NULL
)

Arguments

description

Character. Description of what the script does.

data_source

Character. Optional. Enter the sources of data used in this script — name the dataset or survey, not a file path (e.g. "Current Population Survey (BLS)").

pin_to_top

Logical. Pin this script to the top of the trail. Useful for a main.R that sources other scripts — keeps it visible at the top of ⁠_tinytrail.yaml⁠ regardless of alphabetical order. Default FALSE.

record_runtime

Logical. Record elapsed time on exit. Default TRUE.

name

Character. Override the auto-detected script name. Intended for use in tests and non-standard execution environments where auto-detection is unavailable.

auto

Logical. Automatically intercept common write functions and record their output paths. Default TRUE. Set to FALSE to use explicit tinytrail_write() calls instead.

extra_hooks

A list with elements fn and arg specifying additional write functions to intercept when auto = TRUE. fn is a character vector of function names ("my_save" for a script-level function, or "pkg::fn" for a package function). arg is a character vector of the corresponding file-path argument names. Functions from packages that are not installed are silently skipped.

Details

By default (auto = TRUE) common write functions (write.csv, saveRDS, readr::write_csv, ggplot2::ggsave, etc.) are hooked automatically so their output file paths are captured without any tinytrail_write() wrapper. Set auto = FALSE to use explicit tinytrail_write() calls instead.

Value

name (the script name), invisibly. Called for its side effect of creating or updating the YAML trail file in the project root.

See Also

tinytrail_write() to record output paths explicitly, tinytrail_dict() to capture a data dictionary.

Examples


withr::with_tempdir({
  writeLines("Package: testproject\nVersion: 0.1.0", "DESCRIPTION")

  tinytrail(
    description    = "Clean and summarise survey data",
    data_source    = "Current Population Survey (BLS)",
    record_runtime = FALSE,
    name           = "clean.R"
  )
  write.csv(mtcars, "clean.csv")
  png("age_dist.png"); hist(mtcars$mpg, main = "MPG"); dev.off()
})

Add a data frame to the project data dictionary

Description

Place at the end of a read/clean pipeline to capture column names and optionally sample values. Returns the data frame unchanged.

Usage

tinytrail_dict(
  df,
  df_name = NULL,
  sample_values = TRUE,
  sample_string_length = 18L
)

Arguments

df

A data frame.

df_name

Character. Label for this entry in the data dictionary. Defaults to the variable name of df as written in the calling code (e.g. mtcars |> tinytrail_dict() records as "mtcars"). Override when the expression is not a simple name or when you need a custom label.

sample_values

Logical. Record 5 sample values per column. Default TRUE.

sample_string_length

Integer or Inf. Maximum characters per sample value before truncating with "...". Default 18L.

Details

Requires tinytrail() to have been called first in the same session.

Value

df, invisibly.

See Also

tinytrail() to initialise the trail, tinytrail_write() to record output paths explicitly.

Examples


withr::with_tempdir({
  writeLines("Package: testproject\nVersion: 0.1.0", "DESCRIPTION")

  tinytrail("Analyse data", name = "analysis.R", record_runtime = FALSE)
  dat <- mtcars |> tinytrail_dict(df_name = "cars")
})

Record an output file path in the trail

Description

Wraps the file path argument of any save call. Registers the path under the current script's trail entry and returns the path unchanged, so it can be dropped inline into any save function.

Usage

tinytrail_write(file)

Arguments

file

Character. Path to the output file.

Details

Requires tinytrail() to have been called first in the same session.

Value

file, invisibly.

See Also

tinytrail() to initialise the trail, tinytrail_dict() to capture a data dictionary.

Examples


withr::with_tempdir({
  writeLines("Package: testproject\nVersion: 0.1.0", "DESCRIPTION")

  tinytrail("Process raw data", name = "analysis.R", record_runtime = FALSE,
            auto = FALSE)
  write.csv(mtcars, tinytrail_write("clean.csv"))
  saveRDS(lm(mpg ~ wt, mtcars), tinytrail_write("model.rds"))
})