List files and directories in a GitHub repository

Lists file and directory names found under rev:path in a GitHub repository via GitHub's GraphQL API.

Usage

gh_dir_ls(
  owner,
  name,
  path = ".",
  rev = "HEAD",
  recurse = TRUE,
  incl_dirs = TRUE,
  incl_files = TRUE
)

Arguments

owner

Repository owner's GitHub user or organization name. A character scalar.

name

Repository name. A character scalar.

path

Path to a directory, relative to the repository root. A character scalar.

rev

Git revision expression matching the desired Git tree object, e.g. a branch or tag name or another symbolic reference like "HEAD@{yesterday}" or "HEAD~10". A character scalar.

recurse

Whether or not to recurse into subdirectories of path.

incl_dirs

Whether or not to list directories (and subdirectories if recurse = TRUE).

incl_files

Whether or not to list files (also inside subdirectories if recurse = TRUE).

Value

A character vector of paths to the files and subdirectories found under rev:path, relative to the repository root.

Details

Works for both public and private repositories, for the latter you just need to set up a sufficiently authorized GitHub Personal Access Token (PAT).

Note that an empty character vector is returned in case path is invalid or no file/directory exists underneath path.

See also

Other GitHub functions: gh_release_latest(), gh_releases(), gh_text_file(), gh_text_files()

Examples

# you can opt-out from directory recursion
yay::gh_dir_ls(owner = "salim-b",
               name = "pal",
               recurse = FALSE) |>
  pal::cat_lines()
#> .Rbuildignore
#> .ackrc
#> .gitignore
#> .rgignore
#> DESCRIPTION
#> LICENSE.md
#> NAMESPACE
#> R
#> README.Rmd
#> README.md
#> Rmd
#> TODO.md
#> data-raw
#> docs
#> inst
#> man
#> netlify.toml
#> pal.Rproj
#> pkgdown
#> tests

# you can list only files in a directory
yay::gh_dir_ls(owner = "salim-b",
               name = "pal",
               path = "tests",
               incl_dirs = FALSE) |>
  pal::cat_lines()
#> tests/testthat.R
#> tests/testthat/test-cli.R
#> tests/testthat/test-git.R
#> tests/testthat/test-internal.R
#> tests/testthat/test-lists.R
#> tests/testthat/test-md.R
#> tests/testthat/test-misc.R
#> tests/testthat/test-rmd_knitr.R
#> tests/testthat/test-rpkgs.R
#> tests/testthat/test-stat.R
#> tests/testthat/test-string.R
#> tests/testthat/test-tibble.R

# or you can list only directories in a directory
yay::gh_dir_ls(owner = "salim-b",
               name = "pal",
               path = "tests",
               incl_files = FALSE) |>
  pal::cat_lines()
#> tests/testthat