From 151f1e9d8caf417d26534c7621e4e9b5bae4a90c Mon Sep 17 00:00:00 2001
From: Varun Patil <radialapps@gmail.com>
Date: Fri, 29 Sep 2023 09:50:49 -0700
Subject: [PATCH] docs: document OCC commands

closes #772

Signed-off-by: Varun Patil <radialapps@gmail.com>
---
 docs/occ-commands.md  | 67 +++++++++++++++++++++++++++++++++++++++++++
 lib/Command/Index.php |  6 ++--
 mkdocs.yml            |  1 +
 3 files changed, 71 insertions(+), 3 deletions(-)
 create mode 100644 docs/occ-commands.md

diff --git a/docs/occ-commands.md b/docs/occ-commands.md
new file mode 100644
index 00000000..ada0567b
--- /dev/null
+++ b/docs/occ-commands.md
@@ -0,0 +1,67 @@
+---
+description: Documentation for Memories OCC commands
+---
+
+# OCC commands
+
+Memories provides several OCC commands for administration. For usage of the `occ` command line, refer [here](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html) for more information.
+
+!!! warning "OCCWeb"
+
+    The OCCWeb app is deprecated, and will not work with Memories. You must use the `occ` command line.
+
+## `occ memories:index`
+
+This is the basic command for indexing metadata in files. You don't need to run this in a cron job since this is handled as a background job automatically. You can use the index command to speed up indexing if you just installed the app or if you have a lot of files that are not indexed yet.
+
+!!! tip "Indexing in parallel"
+
+    You can run multiple processes of indexing in parallel, e.g. `for i in {1..4}; do (occ memories:index &); done`. This will speed up indexing significantly.
+
+```
+Usage:
+  memories:index [options]
+
+Options:
+  -u, --user=USER       Index only the specified user
+  -g, --group=GROUP     Index only specified group
+      --folder=FOLDER   Index only the specified folder (relative to the user's root)
+  -f, --force           Force refresh of existing index entries
+      --clear           Clear all existing index entries
+      --skip-cleanup    Skip cleanup step (removing index entries with missing files)
+```
+
+!!! info "Re-indexing"
+
+    Running the command again will NOT reindex everything. It will only index new files and update the index for changed files.
+    If you really want to reindex everything, use the `--force` option or `--clear` to truncate all Memories tables before the index.
+
+## `occ memories:places-setup`
+
+Download and index the planet database. The planet database is the border map of the entire world and is used for reverse geocoding (not for the map). To use reverse geocoding, MySQL or Postgres is required.
+
+```
+Usage:
+  memories:places-setup [options]
+
+Options:
+  -r, --recalculate     Only recalculate places for existing files
+```
+
+## `memories:migrate-google-takeout`
+
+Migrate Google Takeout JSON metadata to the files as EXIF data.
+
+```
+Usage:
+  memories:migrate-google-takeout [options]
+
+Options:
+  -o, --override        Override existing EXIF metadata
+  -u, --user=USER       Migrate only for the specified user
+  -f, --folder=FOLDER   Migrate only for the specified folder
+```
+
+!!! warning "Updates to files"
+
+    This command will modify the files in the user's data directory. Make sure you have a backup!
diff --git a/lib/Command/Index.php b/lib/Command/Index.php
index 643c2bbb..2638c6ec 100644
--- a/lib/Command/Index.php
+++ b/lib/Command/Index.php
@@ -96,13 +96,13 @@ class Index extends Command
     {
         $this
             ->setName('memories:index')
-            ->setDescription('Generate photo entries')
+            ->setDescription('Index the metadata in files')
             ->addOption('user', 'u', InputOption::VALUE_REQUIRED, 'Index only the specified user')
+            ->addOption('group', 'g', InputOption::VALUE_REQUIRED, 'Index only specified group')
             ->addOption('folder', null, InputOption::VALUE_REQUIRED, 'Index only the specified folder (relative to the user\'s root)')
             ->addOption('force', 'f', InputOption::VALUE_NONE, 'Force refresh of existing index entries')
             ->addOption('clear', null, InputOption::VALUE_NONE, 'Clear all existing index entries')
-            ->addOption('skip-cleanup', null, InputOption::VALUE_NONE, 'Skip cleanup step')
-            ->addOption('group', 'g', InputOption::VALUE_REQUIRED, 'Index only specified group')
+            ->addOption('skip-cleanup', null, InputOption::VALUE_NONE, 'Skip cleanup step (removing index entries with missing files)')
         ;
     }
 
diff --git a/mkdocs.yml b/mkdocs.yml
index e3466a4d..24714000 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -44,6 +44,7 @@ nav:
       - 'hw-transcoding.md'
       - 'troubleshooting.md'
       - 'system-config.md'
+      - 'occ-commands.md'
   - Support:
       - 'faq.md'
       - 'changelog.md'