From 6ee9aa5fed7f86dc7cbcb1790f5bd765cf58db3f Mon Sep 17 00:00:00 2001
From: Mossa <cgmossa@gmail.com>
Date: Fri, 27 Feb 2026 09:14:21 +0100
Subject: [PATCH 1/3] wp: initial `dvs delete` spec

---
 spec/delete.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 spec/delete.md

diff --git a/spec/delete.md b/spec/delete.md
new file mode 100644
index 0000000..7db51a4
--- /dev/null
+++ b/spec/delete.md
@@ -0,0 +1,43 @@
+# `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()
+)
+```
+
+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.

From 6e9d217bd5ada40f0cdba00281674f5c64330cd4 Mon Sep 17 00:00:00 2001
From: Mossa <cgmossa@gmail.com>
Date: Fri, 27 Feb 2026 11:14:03 +0100
Subject: [PATCH 2/3] wp: introduced `dvs delete`

---
 spec/delete.md |  5 +++--
 spec/remove.md | 15 +++++++++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)
 create mode 100644 spec/remove.md

diff --git a/spec/delete.md b/spec/delete.md
index 7db51a4..fc4fd0a 100644
--- a/spec/delete.md
+++ b/spec/delete.md
@@ -29,8 +29,9 @@ Unlike `dvs get`, providing no arguments to `dvs delete` will not delete all the
 
 ```r
 dvs_delete <- function(
-  files = character(), 
-  glob = character()
+  files = character(),
+  glob = character(),
+  delete_cached = TRUE
 )
 ```
 
diff --git a/spec/remove.md b/spec/remove.md
new file mode 100644
index 0000000..8593eb6
--- /dev/null
+++ b/spec/remove.md
@@ -0,0 +1,15 @@
+# dvs remove / `dvs remove` / `dvs::dvs_remove`
+
+Goal: Provide a way to untrack a file without deleting it from the project.
+
+## R
+
+Functionally an alias to `dvs_delete` by
+
+```r
+dvs_remove <- function(...) {
+    dvs_delete(delete_cached=FALSE, ...)
+}
+# alias
+dvs_untrack <- dvs_remove
+```

From 698715e969ab92735a5634b5e946799c529c44b4 Mon Sep 17 00:00:00 2001
From: Mossa <cgmossa@gmail.com>
Date: Fri, 27 Feb 2026 11:22:29 +0100
Subject: [PATCH 3/3] update `dvs rm`

---
 spec/remove.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/spec/remove.md b/spec/remove.md
index 8593eb6..ffa2b9c 100644
--- a/spec/remove.md
+++ b/spec/remove.md
@@ -2,6 +2,26 @@
 
 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