summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
author魏曹先生 <1992414357@qq.com>2026-01-03 15:17:56 +0800
committer魏曹先生 <1992414357@qq.com>2026-01-03 15:17:56 +0800
commit7f3e51cf19e23292ab2087f521408c70c92f12fe (patch)
tree227b5d8e7571367113d3a4084b46755db41e13f3
parent6de928360b8be82e06b7eaea67654d557283511a (diff)
Update track command help text to clarify its conceptual model
The help text for `jv track` has been rewritten to emphasize its role as a declaration of fact rather than a simple upload/download operation. The new text explains the three scenarios: creation (when a file is untracked), update (when you hold the file), and synchronization (when you don't hold the file). The Chinese locale has been updated accordingly.
-rw-r--r--locales/help_docs/en.yml31
-rw-r--r--locales/help_docs/zh-CN.yml23
2 files changed, 37 insertions, 17 deletions
diff --git a/locales/help_docs/en.yml b/locales/help_docs/en.yml
index 02d371c..7b2d200 100644
--- a/locales/help_docs/en.yml
+++ b/locales/help_docs/en.yml
@@ -381,18 +381,27 @@ jv:
- File's version in `ref`
track: |
- **Track or Pull Files**
+ **Track Files to Latest Fact**
**Usage**: jv track <FILE_PATH>
- **Example**: jv track src/main.rs
- 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
+ It is not uploading, nor downloading,
+ but a declaration of the result regarding [[cyan]]"which version should be considered fact"[[/]].
- Tracking files is the basic operation of version control, ensuring your upstream and local files are always up to date.
+ **Creation**
+ When there is an untracked file in the workspace, that file does not yet exist in the recognized fact.
+ Executing track will create the factual version of this file, write it to your sheet, and grant you editing rights.
+ At this point, you are **the author of this fact**.
+
+ **Update**
+ When you hold a file and edit based on the current latest fact,
+ the version in your workspace will be considered the new latest fact.
+ Executing track will **update this fact to the upstream**.
+
+ **Synchronization**
+ When you do not hold the file, edit based on outdated facts, or the file does not exist locally,
+ your modifications do not have factual validity; everything follows the upstream latest version.
+ Executing track will **synchronize the upstream fact to local**.
+ To overwrite local modifications, you must explicitly specify `--overwrite`.
hold: |
**Hold Files: Obtain File Edit Rights from Upstream Vault**
@@ -417,8 +426,8 @@ jv:
move: |
**Move Mapping**
**Usage**:
- jv move <mapping> <target_mapping> - Modify upstream mapping
- jv move <mapping> --erase - Erase upstream mapping
+ jv move <MAPPING> <TARGET_MAPPING> - Modify upstream mapping
+ jv move <MAPPING> --erase - Erase upstream mapping
**Examples**:
jv move draft/character.png done/character.png - Move mapping
diff --git a/locales/help_docs/zh-CN.yml b/locales/help_docs/zh-CN.yml
index 665283b..7d93620 100644
--- a/locales/help_docs/zh-CN.yml
+++ b/locales/help_docs/zh-CN.yml
@@ -373,15 +373,26 @@ jv:
- 文件在 `ref` 中的版本
track: |
- **追踪或拉取文件**
+ **追踪文件至最新事实**
**用法**:jv track <文件路径>
- **例如**:jv track src/main.rs
- 追踪新文件时,会创建并上传 “第一版本”,然后自动持有该文件的编辑权
- 追踪 *已持有* 文件时会上传新版本到上游库,以更新至最新版本。
- 追踪 *未持有* 或 *不存在* 的远程文件时,会下载或更新本地文件版本至最新
+ 它不是上传,也不是下载,而是对 [[cyan]]“哪一个版本应被视为事实”[[/]] 的结果声明。
- 追踪文件是版本控制的基础操作,确保您的上游和本地文件时刻都是最新的
+ **创建**
+ 当工作区存在未被追踪的文件时,该文件尚不存在于公认事实中
+ 执行追踪将创建该文件的事实版本,写入您的表,并授予您编辑权
+ 此时,您是 **该事实的撰写者**
+
+ **更新**
+ 当您持有文件,且基于当前最新事实进行编辑时,
+ 您工作区中的版本将被视为新的最新事实
+ 执行追踪将 **更新该事实到上游**
+
+ **同步**
+ 当您不持有文件、基于过期事实编辑,或本地不存在该文件时,
+ 您的修改不具备事实效力,一切以上游最新版为准
+ 执行追踪将 **同步上游事实到本地**
+ 若需覆盖本地修改,必须显式指定 `--overwrite`
hold: |
**拿取文件:从上游库获得该文件的编辑权**