Create a Directory

Create a directory if it does not yet exist.

Usage

create_dir(dir = fs::path(".", "output"), add_date = TRUE)

Arguments

dir

character string containing a valid path, see 'Details' and the section 'Notes on Paths' below.

add_date

TRUE or FALSE: create a subdirectory in dir with the current date in the format YYYY_mm_dd?

Value

A character string with the absolute normalised path to the requested directory, returned invisibly, see the section 'Notes on Paths' and the 'Examples' below.

By default a subdirectory with the current date in the format YYYY_mm_dd is created in directory output below the working directory.

An error is thrown if the attempt to create a directory fails, for example because dir points to an existing file instead of to an directory.

Details

The path in dir is interpreted as a relative path to the directory that should be created, starting from the working directory, see the section 'Notes on Paths' below.

Side Effects

The directory indicated by the returned path is created if it does not yet exist.

Notes on Paths

The file separator is a backslash (\) on Windows but a forward slash (/) on other operating systems: use file.path() or fs::path() to construct paths in a platform-independent way and .Platform$file.sep to get the file separator used on the current platform.

Furthermore, the backslash is also used as an escape character in R, such that backslashes need to be escaped in R code by doubling them. Use cat(x) to omit the escape characters to see how x would be printed.

The working directory can be indicated by a single dot (".") and the parent directory can be indicated by two dots ("..").

relative paths start from the working directory. In contrast, absolute paths start from the root directory and thus give the complete path, such that the path still points to the same directory if the working directory changes.

Paths can be normalised, e.g., through normalizePath() or fs::path_norm() (which is also called by fs::path_abs()). On case-insensitive file systems, this also adjusts the case to match names of directories that are already present.

See also

checkinput::is_path() to check if a path is valid, with extensive references about file paths and directories; create_tempdir() for a safe way to create temporary directories; create_file_path() to create a file path and creating the indicated directory if it does not yet exist; fs::dir_exists() and fs::dir_create() (with its base-equivalent dir.create()) used by this function.

Other functions to handle paths and directories: create_file_path(), create_tempdir(), get_file_path()

Examples

# Use a temporary directory to not write in the user's directory
my_tempdir <- create_tempdir(prefix = "examplecreatedir")

# Create directory 'dir_one' inside this temporary directory
res_dir_one <- create_dir(dir = fs::path(my_tempdir, "dir_one"),
                          add_date = FALSE)
fs::dir_exists(res_dir_one) # TRUE
#> /tmp/RtmpmaAUni/examplecreatedir1aa921157838/dir_one 
#>                                                 TRUE 

# An attempt to create a directory that already exists does
# not change any directory and the same directory is returned.
res_dir_one_v2 <- create_dir(
  dir = fs::path(my_tempdir, "dir_one"),
  add_date = FALSE)
identical(res_dir_one, res_dir_one_v2) # TRUE
#> [1] TRUE

# On case-insensitive file systems, the directories
# 'res_dir_ONE' and 'res_dir_one' are the same directory. On
# case-sensitive file systems they are different directories.
res_dir_ONE <- create_dir(dir = fs::path(my_tempdir, "dir_ONE"),
                          add_date = FALSE)
identical(res_dir_one, res_dir_ONE)
#> [1] FALSE

# Create directory 'dir_two' with a subdirectory containing
# the current date
res_dir_date <- create_dir(
  dir = fs::path(my_tempdir, "dir_date"), add_date = TRUE)
fs::dir_exists(res_dir_date) # TRUE
#> /tmp/RtmpmaAUni/examplecreatedir1aa921157838/dir_date/2026_10_22 
#>                                                             TRUE 

# Cleaning up
unlink(my_tempdir, recursive = TRUE)
rm(my_tempdir, res_dir_one, res_dir_one_v2,
   res_dir_date, res_dir_ONE)