From 537eed2fb8c584ce14adbd922b3fcf0fa30c2730 Mon Sep 17 00:00:00 2001
From: dberenbaum <dave@iterative.ai>
Date: Fri, 5 May 2023 12:15:04 -0400
Subject: [PATCH] data status: update remote flags

---
 content/docs/command-reference/data/status.md | 38 +++++++++++++++----
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/content/docs/command-reference/data/status.md b/content/docs/command-reference/data/status.md
index 43b852af12..88290170c0 100644
--- a/content/docs/command-reference/data/status.md
+++ b/content/docs/command-reference/data/status.md
@@ -15,7 +15,8 @@ For the status of <abbr>data pipelines</abbr>, see `dvc status`.
 usage: dvc data status [-h] [-q | -v]
                        [--granular] [--unchanged]
                        [--untracked-files [{no,all}]]
-                       [--json] [--remote-refresh]
+                       [--json]
+                       [--not-in-remote] [--no-remote-refresh]
 ```
 
 ## Description
@@ -63,8 +64,7 @@ DVC uncommitted changes:
 - _Not in remote_ indicates that there are file hashes in `.dvc` or `dvc.lock`
   files, but the corresponding <abbr>remote</abbr> files are missing. This may
   happen after adding new files into dvc but before using `dvc push` to upload
-  the data; or after using `dvc gc -c`; or if index for remote is out-of-date,
-  in which case you should use `--remote-refresh` flag to refresh it.
+  the data; or after using `dvc gc -c`.
 
 - _DVC committed changes_ are new, modified, or deleted tracked files or
   directories that have been [committed to DVC]. These may be ready for
@@ -97,7 +97,10 @@ default but this can be enabled with the `--granular` flag.
 
 - `--unchanged` - show unchanged DVC-tracked files.
 
-- `--remote-refresh` - refresh remote index.
+- `--not-in-remote` - show files that are missing from the <abbr>remote</abbr>.
+
+- `--no-remote-refresh` - use cached <abbr>remote</abbr> index (don't check
+  remote). Only has an effect along with `--not-in-remote`.
 
 - `--json` - prints the command's output in easily parsable JSON format, instead
   of a human-readable output.
@@ -142,10 +145,6 @@ Not in cache:
   (use "dvc fetch <file>..." to download files)
         data/data.xml
 
-Not in remote:
-  (use "dvc push <file>..." to upload files)
-        data/data.xml
-
 DVC committed changes:
   (git commit the corresponding dvc files to update the repo)
         modified: data/features/
@@ -198,3 +197,26 @@ DVC uncommitted changes:
 Now there's more information in _DVC committed changes_ regarding the changes in
 `data/features`. From the output, it shows that there is a new file added to
 `data/features`: `data/features/foo`.
+
+## Example: Remote status
+
+```cli
+$ dvc data status --not-in-remote
+Not in cache:
+  (use "dvc fetch <file>..." to download files)
+        data/data.xml
+
+Not in remote:
+  (use "dvc push <file>..." to upload files)
+        data/data.xml
+
+DVC committed changes:
+  (git commit the corresponding dvc files to update the repo)
+        modified: data/features/
+
+DVC uncommitted changes:
+  (use "dvc commit <file>..." to track changes)
+  (use "dvc checkout <file>..." to discard changes)
+        deleted: model.pkl
+(there are other changes not tracked by dvc, use "git status" to see)
+```