dvs init

dvs init creates a dvs.toml project file in the root directory and a metadata folder (.dvs by default). It records where file contents are stored and how they are compressed.

The first argument names the storage backend. dvs init local <PATH> stores file contents in a directory, such as a shared drive. dvs init server stores them on a dvs server, and is not covered on this page. A plain dvs init <PATH> stops with "dvs init needs a backend before the storage path".

Usage: dvs init local [OPTIONS] <PATH>

Arguments:
  <PATH>  Where the data will be stored

Options:
      --root-dir <ROOT_DIR>                           Project root (default: cwd)
      --metadata-folder-name <METADATA_FOLDER_NAME>   Metadata folder (default: .dvs)
      --group <GROUP>                                 Unix group for storage and files
      --no-compression                                Disable compression (default: zstd)
  -h, --help                                          Print help

Global Options:
      --json                                          Output results as JSON
      --emit-events                                   Stream results and progress as NDJSON
      --threads <THREADS>                             Threads (0 = auto-detect)

🔗Options

🔗Setup

Each init example runs in its own directory, because init fails if a dvs.toml already exists in the target root.

options(width = 1000)
base <- tempfile("dvs_init_")
dir.create(base)
Sys.setenv(DVS_BASE = base)

🔗Storage path

The positional argument is the storage directory. init writes dvs.toml in the project root and records the storage path under [backend].

cd "$DVS_BASE"
mkdir -p basic/proj basic/store
cd basic/proj
dvs init local ../store
cat dvs.toml

DVS Initialized at /private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpiutLRg/dvs_init_66601274b747/basic/proj
compression = "zstd"

[backend]
path = "/private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpiutLRg/dvs_init_66601274b747/basic/store"
group = "staff"

🔗--root-dir

Initialize a project rooted at a path other than the current directory. dvs.toml is created in the root, not in the working directory.

cd "$DVS_BASE"
mkdir -p rootdir/proj rootdir/store
dvs init local rootdir/store --root-dir rootdir/proj
ls rootdir/proj/dvs.toml

DVS Initialized at rootdir/proj
rootdir/proj/dvs.toml

🔗--metadata-folder-name

Use a metadata folder name other than .dvs. The name is recorded in dvs.toml so later commands find it.

cd "$DVS_BASE"
mkdir -p meta/proj meta/store
cd meta/proj
dvs init local ../store --metadata-folder-name .meta
ls -a

DVS Initialized at /private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpiutLRg/dvs_init_66601274b747/meta/proj
.
..
.meta
dvs.toml

🔗--group

Set a Unix group on the storage directory and stored files for shared access. The group must exist and you must be a member. This example is not executed; it requires a specific group on the host.

cd "$DVS_BASE"
mkdir -p group/proj group/store
cd group/proj
dvs init local ../store --group rstudio

DVS Initialized at /path/to/group/proj

The chosen group is written to dvs.toml under [backend].

🔗--no-compression

Disable zstd compression. The setting is recorded in dvs.toml and applied to files added under this project.

cd "$DVS_BASE"
mkdir -p nocomp/proj nocomp/store
cd nocomp/proj
dvs init local ../store --no-compression
cat dvs.toml

DVS Initialized at /private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpiutLRg/dvs_init_66601274b747/nocomp/proj
compression = "none"

[backend]
path = "/private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpiutLRg/dvs_init_66601274b747/nocomp/store"
group = "staff"

The R function uses an enum instead of a boolean: --no-compression maps to dvs_init(compression = "none"). See dvs_init().

🔗--threads

Override the auto-detected thread count for this command.

cd "$DVS_BASE"
mkdir -p threads/proj threads/store
cd threads/proj
dvs init local ../store --threads 2

DVS Initialized at /private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpiutLRg/dvs_init_66601274b747/threads/proj

🔗--json

Emit the result as JSON instead of a status line. Every command prints one versioned object with the same top-level fields: v (the format version), command, outcome, error (null unless the command failed) and timings. The commands that act on files add counts and a files list.

cd "$DVS_BASE"
mkdir -p jsonex/proj jsonex/store
cd jsonex/proj
dvs init local ../store --json

{"command":"init","dry_run":false,"duration_ms":1,"error":null,"finished_at":"2026-10-30T11:10:09.871Z","outcome":"complete","project_root":"/private/var/folders/_x/bq8vb1b156sgl363l71by61h0000gn/T/RtmpiutLRg/dvs_init_66601274b747/jsonex/proj","started_at":"2026-10-30T11:10:09.869Z","v":1}

🔗Notes

init errors if a dvs.toml already exists in the target root. A dvs.toml in a parent directory does not block a nested project; you can have multiple projects in one Git repository. See The dvs.toml project file.

🔗Differences from R

The R function is dvs_init(). It takes compression = c("zstd", "none") rather than the --no-compression flag, and has no --threads or --json; threads are set process-wide with set_dvs_threads().

🔗See also

• dvs add, dvs status, dvs get
• The dvs.toml project file
• Storage and meta files