update: help documentation

Expand help docs with new commands and improved descriptions

2 files changed, 324 insertions, 77 deletions

diff --git a/locales/help_docs/en.yml b/locales/help_docs/en.yml
index 746fe4c..538f15f 100644
--- a/locales/help_docs/en.yml
+++ b/locales/help_docs/en.yml
@@ -2,6 +2,9 @@ common:
   confirm: |
     Confirm to perform the above operation? (Y/n):
 
+  word:
+    version: Version
+
 jvv:
   version:
     header: |
@@ -171,23 +174,24 @@ jv:
     account_not_exist: |
       The account `%{account}` set for the current workspace is not registered on your computer
 
+    outdated: |
+      Workspace info has not been updated for %{hour} hours %{minutes} minutes
+      Use `jv u` to get the latest information
+
   help: |
     **JustEnoughVCS**
     This program connects to upstream vaults to synchronize and commit changes to local workspace files for collaborative work.
 
     **ALIASES**:
-      jv u                          - Download latest information
-      jv t                          - Track files
-      jv mv -a                      - Auto-move files
-      jv [in|out]                   - Import or export files
-
-    **WORKSPACE**:
-      create <NAME>                 - Create workspace
-      init                          - Create workspace in current directory
+      jv u                          - Download latest information              [REMOTE]
+      jv t                          - Track files                              [REMOTE]
+      jv a                          - Align files to sheet
+      jv [in|out]                   - Import or export files                   [REMOTE]
 
     **UPSTREAM VAULT**:
-      direct <UPSTREAM>             - Direct workspace to upstream vault
+      direct <UPSTREAM>             - Direct workspace to upstream vault       [REMOTE]
       unstain                       - Unstain workspace, clear association
+      update                        - Download latest information              [REMOTE]
 
     **ACCOUNTS**:
       account [list|as|add|remove|movekey]
@@ -197,31 +201,32 @@ jv:
         remove  <ACCOUNT_NAME>      - Remove account from computer
         movekey <NAME> <KEY_FILE>   - Move private key file to specified account
 
-    **CONTEXT**：
-      here                          - Display path information
-
-    **SYNC**:
-      update - Download latest information
-
     **SHEETS**:
-      sheet [list|use|exit|make|drop]
+      sheet [list|use|exit|make|drop|align]
         list                        - List all sheets
         use                         - Use sheet, start work
         exit                        - Exit sheet, clear current modifications
-        make                        - Create a new sheet for yourself
-        drop                        - Drop the sheet for others to use
+        make                        - Create a new sheet for yourself          [REMOTE]
+        drop                        - Drop the sheet for others to use         [REMOTE]
+        align                       - Align files to sheet                     [REMOTE]
 
-    **FILE TRANSFER**
-      import <PACKAGE_NAME>         - Import files from import area
-      import <REFERENCE_SHEET_PATH> - Import files from reference sheet
-      export <FILE> <SHEET_NAME>    - Export files to other sheets
+    **CONTEXT**:
+      here                          - Display path information
+      status                        - Display current sheet status information
+
+    **FILE TRANSFER**:
+      import <PACKAGE_NAME>         - Import files from import area            [REMOTE]
+      import <REFERENCE_SHEET_PATH> - Import files from reference sheet        [REMOTE]
+      export <FILE> <SHEET_NAME>    - Export files to other sheets             [REMOTE]
 
-    **FILE OPERATIONS**
-      move <FILE> <TO>              - Safely rename files
+    **FILE OPERATIONS**:
+      move  <FILE> <TO>             - Safely rename files
       move auto                     - Automatically handle local file moves or renames
-      track <FILE>                  - Track and upload files to upstream vault
+      track <FILE>                  - Track files to latest version            [REMOTE]
+      hold  <FILE>                  - Hold, sync and lock file                 [REMOTE]
+      throw <FILE>                  - Throw, sync and unlock file              [REMOTE]
 
-    **DOCUMENTATION**
+    **DOCUMENTATION**:
       docs list                     - List all available documentation
       docs <DOC_NAME>               - View content of specified documentation
 
@@ -252,6 +257,12 @@ jv:
     jv sheet make <SHEET_NAME> - Create a new sheet for yourself
     jv sheet drop <SHEET_NAME> - Drop the sheet for others to use
 
+    **Align struct**：
+    jv sheet align --list - View all items that need alignment
+    jv sheet align <ALIGN_TASK> [local/remote] - Choose based on local or remote location
+    jv sheet align [local/remote] - All based on local or remote location
+    jv sheet align - Manually specify alignment method
+
     Sheets are core concepts in JustEnoughVCS, each sheet represents an independent file collection.
     You can switch work between different sheets, or export files from one sheet to another.
 
@@ -283,15 +294,30 @@ jv:
 
     This is a quick way to understand the current state of your workspace directory.
 
+  status: |
+      **Display Current Sheet Status Information**
+      **Usage**: jv status
+
+      Displays the file modification status of the current sheet:
+      - Added, deleted files
+      - Moved files
+      - Modified files
+
+      This is a quick way to understand the current file status of the sheet.
+
   track: |
-    **Track Local Files**
+    **Track or Pull Files**
     **Usage**: jv track <FILE_PATH>
 
     **Example**: jv track src/main.rs
-    First track - Create and upload the "First Version", then automatically hold them
-    Subsequent tracks - Update files with new versions
+    For new files:
+      Create and upload the "First Version", then automatically hold them
+    For *held* files:
+      Upload new versions to the upstream vault to update to the latest version
+    For *unheld* or *non-exist* files:
+      Download or update local file versions to the latest
 
-    Tracking files is the basic operation of version control, ensuring your changes can be synchronized to the upstream vault.
+    Tracking files is the basic operation of version control, ensuring your upstream and local files are always up to date.
 
   hold: |
     **Hold Files: Obtain File Edit Rights from Upstream Vault**
@@ -317,12 +343,10 @@ jv:
     **Move Local Files**
     **Usage**:
     jv move <SOURCE_FILE> <TARGET_LOCATION> - Safely rename or move files
-    jv move auto - Automatically handle local file moves or renames
 
     **Example**:
     jv move old_name.txt new_name.txt
     jv move src/old_dir/file.rs src/new_dir/file.rs
-    jv move auto
 
     Safe move operations preserve file version history, while auto-move detects and handles all renames.
 
@@ -387,6 +411,10 @@ jv:
     Built-in documentation includes JustEnoughVCS usage guides, collaboration paradigms, and best practices.
 
   confirm:
+    unstain: |
+      This operation will disconnect the current workspace from the upstream vault `%{upstream}`
+      If you reconnect to a vault with a mismatched identifier, it will cause serious problems, please operate with caution!
+
     direct: |
       Do you want to direct the current local workspace to the upstream vault %{upstream}?
 
@@ -396,11 +424,38 @@ jv:
           Sheet `%{sheet_name}` is no holder. Take ownership?
           If not, use a different name to create a sheet.
 
+        restore_ref: |
+          You can't just grab the reference sheet, it's the team's shared structure! :)
+
       drop: |
         Are you sure you want to drop sheet `%{sheet_name}`?
         After this, you will not be able to work in the sheet!
 
+    track:
+      prepare: |
+        You are tracking %{file_counts} file(s), these files will follow the following rules
+        1. New files will be uploaded and added to your sheet for management
+        2. For files you held, unless they don't exist locally or versions don't match, upload logic will always be executed
+        3. For files not held unless the version is frozen, download logic will always be executed to get the latest version
+
+        **CURRENT**:
+          **DOWN**: %{old_files} to update, %{download_files} to download
+          **UP**  : %{new_files} to track, %{modified_files} to commit
+
+      need_upload: |
+        Since your specified tracking operation involves uploading, you need to provide detailed description of your changes
+        Ready to commit? Use `jv track <files_to_upload> --work` to start filling in commit information
+        Don't want to use command line editor? Use `jv track <files_to_upload> --msg <commit_message>` to commit directly
+
   fail:
+    std:
+      current_dir: Failed to get current directory
+      current_dir_name: Failed to get current directory name
+      set_current_dir: Failed to set current directory to %{dir}
+
+    format_path: |
+      Failed to format directory %{path}: %{error}.
+
     path_not_found: |
       The directory `%{path}` cannot be found!
 
@@ -413,7 +468,7 @@ jv:
         Error: %{err}
         Cannot recognize *`%{str}`* as a valid address, please check your input!
 
-    from_just_version_control: |
+    from_core: |
       **Error**: `%{err}` (This error is from core call)
 
     account:
@@ -458,10 +513,20 @@ jv:
         Failed to open text editor preview: `%{err}!
         **Tip**: You can also use `jv docs %{docs_name} -d` to print directly
 
-  warn:
-    unstain: |
-      This operation will disconnect the current workspace from the upstream vault `%{upstream}`
-      If you reconnect to a vault with a mismatched identifier, it will cause serious problems, please operate with caution!
+    track:
+      no_selection: |
+        You did not select any files in this operation!
+
+        **Tip**: If you entered content and still see this,
+        it may be because the directory you passed is outside the workspace directory, paths outside the workspace will be ignored
+
+    status:
+      no_sheet_in_use: |
+        You are not using any sheet! Cannot analyze workspace status in this state
+        **Tip**: You can use `jv use <sheet_name>` to select and use a sheet
+
+      analyze: |
+        Failed to analyze local workspace status!
 
   success:
     account:
@@ -484,13 +549,13 @@ jv:
     sheet:
       list:
         your_sheet: |
-          **YOURS**：
+          **YOURS**:
         your_sheet_item: |
           %{number}. %{name}
         your_sheet_item_use: |
           %{number}. %{name} (CURRENT)
         other_sheet: |
-          **OTHERS**：
+          **OTHERS**:
         other_sheet_item: |
           %{number}. %{name} (AT `%{holder}`)
         other_sheet_item_no_holder: |
@@ -520,6 +585,7 @@ jv:
         editing: EDITING
 
       path_info: |
+        Updated in %{minutes} minutes ago
         CURRENT: %{upstream}/%{account}/%{sheet_name}/%{path}
 
       ghost_directory_item_info: |
@@ -565,6 +631,37 @@ jv:
       count_info: |
         %{dir_count} dir(s), %{file_count} file(s). Total %{size}.
 
+    status:
+      header: |
+        Viewing sheet %{sheet_name}. Before tracking file changes, please confirm:
+
+      content: |
+        Structure changes:
+        %{moved_items}%{lost_items}%{created_items}
+        Content modifications:
+        %{modified_items}
+
+      created_item: |
+        +   Created:      %{path}
+
+      lost_item: |
+        -      Lost:      %{path}
+
+      moved_item: |
+        >     Moved:      %{from} -> %{to}
+
+      modified_item: |
+        *  Modified:      %{path}
+
+      invalid_modified_item: |
+        *  Modified:      %{path} (INVALID)
+
+      no_structure_changes: |
+        No structural changes locally
+
+      no_file_modifications: |
+        No local content modifications
+
   result:
     common:
       authroize_failed: |
@@ -594,15 +691,21 @@ jv:
       success: |
         Synchronized to latest information!
 
+      fail:
+        sync_cached_sheet_fail:
+          path_already_exist: |
+            Error syncing upstream information to local: Local path %{path} already exists, but a move operation needs to move an item here.
+            Please try moving the item to a different path, then run `jv update` again
+
     sheet:
       make:
         success: |
           Successfully created sheet `%{name}`!
-          Upstream changed，use `jv update` to get the latest information
+          Upstream changed, use `jv update` to get the latest information
 
         success_restore: |
           Successfully restored sheet `%{name}`!
-          Upstream changed，use `jv update` to get the latest information
+          Upstream changed, use `jv update` to get the latest information
 
         sheet_already_exists: |
           Sheet `%{name}` already exists!
@@ -631,3 +734,22 @@ jv:
 
         not_owner: |
           You are not the holder of sheet `%{name}`, cannot drop it!
+
+    track:
+      done: |
+        Tracked %{count} files to latest!
+        **Total**: %{created} Created, %{updated} Updated, %{synced} Synced
+
+      structure_changes_not_solved: |
+        There are unresolved local structure changes!
+        This indicates there are unconfirmed move or delete operations in your local workspace
+        **Tip**: Use `jv status` to view structure changes
+
+      create_failed:
+        sheet_not_found: |
+          Sheet `%{name}` does not exist in the upstream vault!
+          This means the sheet has been deleted in the upstream vault, or the sheet does not belong to you
+
+        create_file_on_exist_path: |
+          Failed to track and create file!
+          The file path `%{path}` you want to track already exists in the remote sheet, please use a different path for tracking
diff --git a/locales/help_docs/zh-CN.yml b/locales/help_docs/zh-CN.yml
index a7a5be1..2bd91ee 100644
--- a/locales/help_docs/zh-CN.yml
+++ b/locales/help_docs/zh-CN.yml
@@ -2,6 +2,9 @@ common:
   confirm: |
     是否执行上述操作？（Y/n）：
 
+  word:
+    version: 版本
+
 jvv:
   version:
     header: |
@@ -163,20 +166,21 @@ jv:
     account_not_exist: |
       当前工作区设置的账户 `%{account}` 并未注册至您的计算机
 
+    outdated: |
+      工作区内信息已经 %{hour} 小时 %{minutes} 分钟没有更新了
+      请使用 `jv u` 拿到最新信息
+
   help: |
     **JustEnoughVCS 本地工作区命令**
     该程序将连接至上游库，用以同步、提交本地工作区文件的变化，以供协同创作
 
     **常用别名**：
-      jv u 下载最新信息，jv t 追踪文件，jv mv -a 自动移动文件，jv in/out 导入或导出文件
-
-    **工作区**：
-      create <名称>           - 创建工作区
-      init                    - 当前目录创建工作区
+      jv u 下载最新信息，jv t 追踪文件，jv a 对齐文件结构到表，jv in/out 导入或导出文件
 
     **上游库**：
-      direct <上游地址>       - 定向到工作区到上游库
+      direct <上游地址>       - 定向到工作区到上游库            [远程]
       unstain                 - 祛色工作区，清除关联
+      update                  - 同步最新的信息                  [远程]
 
     **账户**：
       account [list|as|add|remove|movekey]
@@ -188,31 +192,32 @@ jv:
 
         movekey <账户> <私钥> - 移动私钥文件到指定账户
 
-    **信息同步**：
-      update                  - 下载最新的信息
-
     **表操作**：
-      sheet [list|use|exit|make|drop]
+      sheet [list|use|exit|make|drop|align]
         list                  - 列出所有表
         use                   - 使用表，并开始工作
         exit                  - 退出表，清除当前修改
-        make                  - 创建新表以供自己使用
-        drop                  - 抛弃表以供他人使用
+        make                  - 创建新表以供自己使用            [远程]
+        drop                  - 抛弃表以供他人使用              [远程]
+        align                 - 对齐文件结构到表                [远程]
 
     **上下文查询**：
       here                    - 显示当前路径的相关信息
+      status                  - 显示当前表的状态信息
 
-    **文件传递**
-      import <文件包名称>     - 从导入区导入文件
-      import <参照表中目录>   - 从参照表导入文件
-      export <文件> <表名称>  - 导出文件到其他表
+    **文件传递**：
+      import <文件包名称>     - 从导入区导入文件                [远程]
+      import <参照表中目录>   - 从参照表导入文件                [远程]
+      export <文件> <表名称>  - 导出文件到其他表                [远程]
 
-    **文件操作**
-      move <文件> <到>        - 安全地重命名文件
-      move auto               - 自动处理本地文件的移动或重命名
-      track <文件>            - 追踪、上传文件到上游库
+    **文件操作**：
+      move  <文件> <到>       - 安全地重命名文件
+      move auto-align         - 将表中记录的映射对齐到实际结构
+      track <文件>            - 跟踪文件内容到最新版本          [远程]
+      hold  <文件>            - 拿取文件，同步版本并获得编辑权  [远程]
+      throw <文件>            - 丢弃文件，同步版本并放弃编辑权  [远程]
 
-    **内建文档**
+    **内建文档**：
       docs list               - 列出所有可用的文档
       docs <文档名称>         - 查看指定文档的内容
 
@@ -244,6 +249,12 @@ jv:
     jv sheet make <表名称> - 为自己创建一张新的表
     jv sheet drop <表名称> - 将表抛弃，以供其他人使用
 
+    **对齐**：
+    jv sheet align --list - 查看所有需要对齐的项目
+    jv sheet align [local/remote] - 全部基于本地位置或远程位置
+    jv sheet align <对齐任务> [local/remote] - 选择基于本地位置或远程位置
+    jv sheet align - 手动指定对齐方式
+
     表是 JustEnoughVCS 中的核心概念，每个表代表一块独立的文件集合
     您可以在不同的表之间切换工作，或者将文件从一张表导出到另一张表
 
@@ -279,15 +290,28 @@ jv:
     这是了解当前工作区目录状态的快速方式
 
 
+  status: |
+    **显示当前表的状态信息**
+    **用法**：jv status
+
+    显示当前表的文件修改状态：
+    - 新增、删除的文件
+    - 移动的文件
+    - 修改的文件
+
+    这是了解当前表文件状态的快速方式
+
+
   track: |
-    **追踪本地的文件**
+    **追踪或拉取文件**
     **用法**：jv track <文件路径>
 
     **例如**：jv track src/main.rs
-    第一次追踪文件时，会创建并上传 “第一版本”，然后自动持有该文件的编辑权
-    后续追踪同一文件时，会更新文件的新版本
+    追踪新文件时，会创建并上传 “第一版本”，然后自动持有该文件的编辑权
+    追踪 *已持有* 文件时会上传新版本到上游库，以更新至最新版本。
+    追踪 *未持有* 或 *不存在* 的远程文件时，会下载或更新本地文件版本至最新
 
-    追踪文件是版本控制的基础操作，确保您的更改能够同步到上游库
+    追踪文件是版本控制的基础操作，确保您的上游和本地文件时刻都是最新的
 
 
   hold: |
@@ -316,12 +340,10 @@ jv:
     **移动本地文件**
     **用法**：
     jv move <源文件> <目标位置> - 安全地重命名或移动文件
-    jv move auto - 自动处理本地文件的移动或重命名
 
     **例如**：
     jv move old_name.txt new_name.txt
     jv move src/old_dir/file.rs src/new_dir/file.rs
-    jv move auto
 
     安全移动操作会保持文件的版本历史，而自动移动会检测并处理所有重命名
 
@@ -392,6 +414,10 @@ jv:
     内建文档包含 JustEnoughVCS 的使用指南、协作范式和最佳实践
 
   confirm:
+    unstain: |
+      此操作将会断开当前工作区与上游库 `%{upstream}` 的关联
+      若重新连接至标识不匹配的库，会导致严重的问题，请谨慎操作！
+
     direct: |
       是否需要将当前本地工作区定向到上游库 %{upstream}？
 
@@ -401,10 +427,37 @@ jv:
           似乎 `%{sheet_name}` 是一张无人认领的表，是否拿到它的所有权？
           如果您不想拿到该表，请使用别的名称建立表
 
+        restore_ref: |
+          您不能直接拿到参照表，它是团队的公共结构 :)
+
       drop: |
         是否要放弃表 `%{sheet_name}` 的所有权，此后，您将无法在表中工作！
 
+    track:
+      prepare: |
+        您正在准备跟踪 %{file_counts} 个文件的变更，这些文件将遵循如下规则：
+        1. 新文件，将被上传并加入您的表中管理
+        2. 已持有文件，除非本地不存在或版本不匹配，否则永远执行上传操作
+        3. 未持有文件，除非冻结版本，否则永远执行下载和更新最新版本
+
+        **当前**：
+        **下行**：%{old_files} 个待更新，%{download_files} 个待下载
+        **上行**：%{new_files} 个待跟踪，%{modified_files} 个待提交
+
+      need_upload: |
+        因为您指定的追踪操作涉及上传，所以需要详细说明您的更改
+        准备好提交了么？使用 `jv track <待上传文件> --work` 开始填写提交信息
+        不想使用命令行编辑器？使用 `jv track <待上传文件> --msg <本次修改信息>` 直接提交
+
   fail:
+    std:
+      current_dir: 无法获得当前目录
+      current_dir_name: 无法获得当前目录的名称
+      set_current_dir: 无法设置到目录 %{dir}
+
+    format_path: |
+      格式化目录 %{path} 失败：%{error}.
+
     path_not_found: |
       您给出的目录 `%{path}` 无法找到！
 
@@ -417,7 +470,7 @@ jv:
         错误：%{err}
         无法将 *`%{str}`* 识别为有效地址，请检查您的输入！
 
-    from_just_version_control: |
+    from_core: |
       **错误**：`%{err}`（该错误来自核心调用）
 
     account:
@@ -458,15 +511,29 @@ jv:
       not_found: 文档 `%{docs_name}` 未找到！
       no_doc_dir: |
         无法找到暂存目录！
-        **提示**：你也可以使用 `jv docs %{docs_name} -d` 直接打印
+        **提示**：您也可以使用 `jv docs %{docs_name} -d` 直接打印
       open_editor: |
         无法打开文本编辑器预览：`%{err}`！
-        **提示**：你也可以使用 `jv docs %{docs_name} -d` 直接打印
+        **提示**：您也可以使用 `jv docs %{docs_name} -d` 直接打印
 
-  warn:
-    unstain: |
-      此操作将会断开当前工作区与上游库 `%{upstream}` 的关联
-      若重新连接至标识不匹配的库，会导致严重的问题，请谨慎操作！
+    track:
+      no_selection: |
+        您未在此次操作中选中任何文件！
+
+        **提示**：如果您输入了内容依旧如此，
+        可能因为您传入的目录在工作区目录以外，工作区之外的路径会被忽略
+
+      parse_fail: |
+        解析传入的参数 `%{param}` 失败！
+        **提示**：请确保您输入的参数格式正确
+
+    status:
+      no_sheet_in_use: |
+        您并没有使用任何一张表！无法在此状态分析工作区状态
+        **提示**：您可以使用 `jv use <表名>` 选择并使用一张表
+
+      analyze: |
+        分析本地工作区的状态失败！
 
   success:
     account:
@@ -509,7 +576,7 @@ jv:
     docs:
       list:
         header: |
-          你可以查阅以下文档：
+          您可以查阅以下文档：
 
         item: |
           %{num}. %{docs_name}
@@ -526,7 +593,8 @@ jv:
         editing: 编辑状态
 
       path_info: |
-        当前：%{upstream}/%{account}/%{sheet_name}/%{path}
+        信息更新自 %{minutes} 分钟前
+        所在：%{upstream}/%{account}/%{sheet_name}/%{path}
 
       ghost_directory_item_info: |
         ? %{directory_name}/
@@ -571,6 +639,38 @@ jv:
       count_info: |
         %{dir_count} 目录、%{file_count} 文件，共计 %{size}
 
+    status:
+      header: |
+        您正在查看表 %{sheet_name} 的状态，在追踪文件变更之前，请确认：
+
+      content: |
+        结构变更：
+        %{moved_items}%{lost_items}%{created_items}
+        内容修改：
+        %{modified_items}
+
+      created_item: |
+        +   创建：      %{path}
+
+      lost_item: |
+        -   丢失：      %{path}
+
+      moved_item: |
+        >   移动：      %{from} -> %{to}
+
+      modified_item: |
+        *   修改：      %{path}
+
+      invalid_modified_item: |
+        *   修改：      %{path} (无法提交的修改)
+
+      no_structure_changes: |
+        无文件结构变更
+
+      no_file_modifications: |
+        本地无内容修改
+
+
   result:
     common:
       authroize_failed: 身份认证失败：%{err}！
@@ -599,6 +699,12 @@ jv:
       success: |
         已同步至最新信息！
 
+      fail:
+        sync_cached_sheet_fail:
+          path_already_exist: |
+            在同步上游信息至本地时发生了错误：本地已存在 %{path}，但是某个移动项需要移动到此处。
+            请尝试移动该项至其他路径，再重新输入 `jv update`
+
     sheet:
       make:
         success: |
@@ -636,3 +742,22 @@ jv:
 
         not_owner: |
           您不是表 `%{name}` 的持有人，无法放弃该表！
+
+    track:
+      done: |
+        追踪 %{count} 个文件至最新！
+        其中，创建 %{created}，更新 %{updated}，同步 %{synced}
+
+      structure_changes_not_solved: |
+        本地有结构变更未解决！
+        这说明您的本地工作区存在未确认的移动或删除操作
+        **提示**：使用 `jv status` 查看结构变更
+
+      create_failed:
+        sheet_not_found: |
+          在上游库中不存在表 `%{name}`！
+          这意味着该表在上游库中已被删除，或该表不属于您
+
+        create_file_on_exist_path: |
+          追踪并创建文件失败！
+          您要追踪的文件路径 `%{path}` 在远程表中已存在，请更换至其他路径追踪