From a2f26846f531b37071dce37c09d92eec95b91f5e Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Mon, 24 Aug 2026 13:34:48 +0800
Subject: [PATCH] docs: clarify staged concurrency behavior

---
 website/docs/en/guide/cli/staged.mdx | 26 +++++++++++++++++++++++++-
 website/docs/zh/guide/cli/staged.mdx | 26 +++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/website/docs/en/guide/cli/staged.mdx b/website/docs/en/guide/cli/staged.mdx
index 582bb55..d3938e6 100644
--- a/website/docs/en/guide/cli/staged.mdx
+++ b/website/docs/en/guide/cli/staged.mdx
@@ -26,12 +26,36 @@ rs staged --allow-empty
 
 ### `--concurrent`
 
-`--concurrent` (or `-p`) sets how many tasks run concurrently; use `false` to run them serially.
+`--concurrent` controls how many tasks may run at the same time. It accepts `true`, `false`, or a positive integer.
+
+When the option is omitted, it defaults to `true`, so `rs staged` runs tasks concurrently without a fixed limit. Set it to `false` to run one task at a time, or use a positive integer to limit the number of concurrent tasks.
 
 ```bash
+# Use the default: run tasks concurrently without a fixed limit
+rs staged
+rs staged --concurrent true
+
+# Run one task at a time
 rs staged --concurrent false
+
+# Run at most four tasks at a time
+rs staged --concurrent 4
+
+# -p is shorthand for --concurrent
+rs staged -p 4
+```
+
+For example:
+
+```ts
+define.staged({
+  '*.ts': ['rs lint --fix', 'rs fmt'],
+  '*.md': 'rs fmt',
+});
 ```
 
+With concurrency enabled, `rs fmt` for Markdown files may run while TypeScript files are being linted. For TypeScript files, `rs fmt` starts only after `rs lint --fix` finishes.
+
 ### `--cwd`
 
 `--cwd` sets the working directory used to run all tasks.
diff --git a/website/docs/zh/guide/cli/staged.mdx b/website/docs/zh/guide/cli/staged.mdx
index 8b71649..4821c3c 100644
--- a/website/docs/zh/guide/cli/staged.mdx
+++ b/website/docs/zh/guide/cli/staged.mdx
@@ -26,12 +26,36 @@ rs staged --allow-empty
 
 ### `--concurrent`
 
-`--concurrent`（或 `-p`）用于设置并发运行的任务数量；设为 `false` 时串行运行。
+`--concurrent` 用于控制同时运行的任务数量，可设置为 `true`、`false` 或正整数。
+
+省略该选项时，默认值为 `true`，`rs staged` 会并发运行任务且不设置固定的并发上限。设为 `false` 时会逐个运行任务；设为正整数时，会限制同时运行的任务数量。
 
 ```bash
+# 使用默认行为：并发运行任务，不设置固定的并发上限
+rs staged
+rs staged --concurrent true
+
+# 每次运行一个任务
 rs staged --concurrent false
+
+# 最多同时运行四个任务
+rs staged --concurrent 4
+
+# -p 是 --concurrent 的缩写
+rs staged -p 4
+```
+
+例如：
+
+```ts
+define.staged({
+  '*.ts': ['rs lint --fix', 'rs fmt'],
+  '*.md': 'rs fmt',
+});
 ```
 
+启用并发时，Markdown 文件的 `rs fmt` 可以在 TypeScript 文件执行 `rs lint --fix` 的同时运行；对于 TypeScript 文件，只有 `rs lint --fix` 完成后才会运行 `rs fmt`。
+
 ### `--cwd`
 
 `--cwd` 用于设置运行所有任务时使用的工作目录。