Initial spec: delete

spec/delete.md

@@ -0,0 +1,44 @@
+# `dvs delete`
+
+Goal: Provide a controlled way to delete / untrack datafiles from DVS.
+
+- delete from dvs storage (backend)
+- delete the metadata file
+- delete the data file
+- delete (and commit) the `*.dvs` metafile from `git` if relevant
+- document the reason behind deletion (audit log entry)
+
+## CLI
+
+```shell
+$ dvs delete [OPTIONS] <PATHS>
+
+Paths:
+    Files to delete from the dvs backend, the current directory, delete metadata file, and also untrack metadata file from `git`
+
+Options:
+    -c, --cached do not delete the files within the project, but delete from backend and the associated metadatafile, plus add audit log entry about the deletion event.
+    -m, --message (optional) message explaining why the file was deleted
+    -h, --help 
+
+```
+
+Unlike `dvs get`, providing no arguments to `dvs delete` will not delete all the tracked files from the repository.
+
+## R package
+
+```r
+dvs_delete <- function(
+  files = character(),
+  glob = character(),
+  delete_cached = TRUE
+)
+```
+
+Aliases: `dvs_delete`, `dvs_remove`, `dvs_rm`.
+
+- `files`: list of files that are to be deleted.
+
+### Non-existing files
+
+Emit a warning, but still remove the files that do exist and are tracked.

spec/remove.md

@@ -0,0 +1,35 @@
+# dvs remove / `dvs remove` / `dvs::dvs_remove`
+
+Goal: Provide a way to untrack a file without deleting it from the project.
+
+## CLI
+
+```sh
+dvs -- Remove files from dvs tracking
+
+Usage:
+    dvs remove <FILES> [OPTIONS]
+    dvs rm <FILES> [OPTIONS] # alias
+
+Files:
+    Paths to tracked files that must be untracked
+
+Options:
+    --json Command output as a JSON format
+    -m, --message (optional) message describing why a file was removed from tracking
+    -h, --help
+```
+
+Files that are not tracked, but provided to `dvs remove` must result in an error. Deletion is a sensitive operation.
+
+## R
+
+Functionally an alias to `dvs_delete` by
+
+```r
+dvs_remove <- function(...) {
+    dvs_delete(delete_cached=FALSE, ...)
+}
+# alias
+dvs_untrack <- dvs_remove
+```