docs: add doc for commands auto-completion (#534)

6067383b · Sandy Xu · GitHub · bd58e9f7 · 6067383b · 6067383b
4 changed file
--- a/docs/en/command_reference.md
+++ b/docs/en/command_reference.md
@@ -4,9 +4,10 @@ There are many commands to help you manage your file system. This page provides

 ## Overview

-If you run `juicefs` by itself, it will print all available subcommands. In addition, you can add `-h/--help` flag after each subcommand to get more information of that subcommand.
+If you run `juicefs` by itself, it will print all available commands. In addition, you can add `-h/--help` flag after each command to get more information of it.

-```
+```bash
+$ juicefs -h
 NAME:
   juicefs - A POSIX file system built on Redis and object storage.

@@ -46,27 +47,60 @@ COPYRIGHT:
   AGPLv3
 ```

-Usage: `juicefs [global options] command [command options] [arguments...]`
+**Note:** If `juicefs` is not placed in your `$PATH`, you should run the script with the path to the script. For example, if `juicefs` is placed in current directory, you should use `./juicefs`. It is recommended to place `juicefs` in your `$PATH` for convenience.
+
+## Auto Completion
+
+To enable commands completion, simply source the script provided within `hack/autocomplete`. For example:
+
+Bash:
+
+```bash
+$ source hack/autocomplete/bash_autocomplete
+```
+
+Zsh:
+
+```bash
+$ source hack/autocomplete/zsh_autocomplete
+```

-Add `-h` or `--help` after all commands, getting arguments list and help information.
+Please note the auto-completion is only enabled for the current session. If you want it for all new sessions, add the `source` command to `.bashrc` or `.zshrc`:
+
+```bash
+$ echo "source path/to/bash_autocomplete" >> ~/.bashrc
+```
+
+or
+
+```bash
+$ echo "source path/to/zsh_autocomplete" >> ~/.zshrc
+```
+
+Alternatively, if you are using bash on a Linux system, you may just copy the script to `/etc/bash_completion.d` and rename it to `juicefs`:
+
+```bash
+$ sudo cp hack/autocomplete/bash_autocomplete /etc/bash_completion.d/juicefs
+$ source /etc/bash_completion.d/juicefs
+```

-***Note:*** If `juicefs` is not placed in your `$PATH`, you should run the script with the path to the script. For example, if `juicefs` is placed in current directory, you should use `./juicefs`. It is recommended to place `juicefs` in your `$PATH` for the convenience.
+**Note:** This feature is implemented base on `github.com/urfave/cli/v2`, you can find more information [here](https://github.com/urfave/cli/blob/master/docs/v2/manual.md#enabling).

-The documentation below gives you detailed information about each subcommand.
+## Commands

-## juicefs format
+### juicefs format

-### Description
+#### Description

 Format a volume. It's the first step for initializing a new file system volume.

-### Synopsis
+#### Synopsis

 ```
 juicefs format [command options] REDIS-URL NAME
 ```

-### Options
+#### Options

 `--block-size value`\
 size of block in KiB (default: 4096)
@@ -104,19 +138,19 @@ overwrite existing format (default: false)
 `--no-update`\
 don't update existing volume (default: false)

-## juicefs mount
+### juicefs mount

-### Description
+#### Description

 Mount a volume. The volume shoud be formatted first.

-### Synopsis
+#### Synopsis

 ```
 juicefs mount [command options] REDIS-URL MOUNTPOINT
 ```

-### Options
+#### Options

 `--metrics value`\
 address to export metrics (default: "127.0.0.1:9567")
@@ -181,36 +215,36 @@ min free space (ratio) (default: 0.1)
 `--cache-partial-only`\
 cache only random/small read (default: false)

-## juicefs umount
+### juicefs umount

-### Description
+#### Description

 Unmount a volume.

-### Synopsis
+#### Synopsis

 ```
 juicefs umount [command options] MOUNTPOINT
 ```

-### Options
+#### Options

 `-f, --force`\
 unmount a busy mount point by force (default: false)

-## juicefs gateway
+### juicefs gateway

-### Description
+#### Description

 S3-compatible gateway.

-### Synopsis
+#### Synopsis

 ```
 juicefs gateway [command options] REDIS-URL ADDRESS
 ```

-### Options
+#### Options

 `--get-timeout value`\
 the max number of seconds to download an object (default: 60)
@@ -254,19 +288,19 @@ do not send usage report (default: false)
 `--no-banner`\
 disable MinIO startup information (default: false)

-## juicefs sync
+### juicefs sync

-### Description
+#### Description

 Sync between two storage.

-### Synopsis
+#### Synopsis

 ```
 juicefs sync [command options] SRC DST
 ```

-### Options
+#### Options

 `--start KEY, -s KEY`\
 the first KEY to sync
@@ -319,49 +353,49 @@ limit bandwidth in Mbps (0 means unlimited) (default: 0)
 `--no-https`\
 do not use HTTPS (default: false)

-## juicefs rmr
+### juicefs rmr

-### Description
+#### Description

 Remove all files in directories recursively.

-### Synopsis
+#### Synopsis

 ```
 juicefs rmr PATH ...
 ```

-## juicefs info
+### juicefs info

-### Description
+#### Description

 Show internal information for given paths or inodes.

-### Synopsis
+#### Synopsis

 ```
 juicefs info [command options] PATH or INODE
 ```

-### Options
+#### Options

 `--inode, -i`\
 use inode instead of path (current dir should be inside JuiceFS) (default: false)


-## juicefs bench
+### juicefs bench

-### Description
+#### Description

 Run benchmark, include read/write/stat big and small files.

-### Synopsis
+#### Synopsis

 ```
 juicefs bench [command options] PATH
 ```

-### Options
+#### Options

 `--block-size value`\
 block size in MiB (default: 1)
@@ -375,19 +409,19 @@ size of small file in MiB (default: 0.1)
 `--small-file-count value`\
 number of small files (default: 100)

-## juicefs gc
+### juicefs gc

-### Description
+#### Description

 Collect any leaked objects.

-### Synopsis
+#### Synopsis

 ```
 juicefs gc [command options] REDIS-URL
 ```

-### Options
+#### Options

 `--delete`\
 deleted leaked objects (default: false)
@@ -398,31 +432,31 @@ compact all chunks with more than 1 slices (default: false).
 `--threads value`\
 number threads to delete leaked objects (default: 10)

-## juicefs fsck
+### juicefs fsck

-### Description
+#### Description

 Check consistency of file system.

-### Synopsis
+#### Synopsis

 ```
 juicefs fsck [command options] REDIS-URL
 ```

-## juicefs profile
+### juicefs profile

-### Description
+#### Description

 Analyze access log.

-### Synopsis
+#### Synopsis

 ```
 juicefs profile [command options] MOUNTPOINT/LOGFILE
 ```

-### Options
+#### Options

 `--uid value, -u value`\
 track only specified UIDs(separated by comma ,)
@@ -436,36 +470,36 @@ track only specified PIDs(separated by comma ,)
 `--interval value`\
 flush interval in seconds (default: 2)

-## juicefs status
+### juicefs status

-### Description
+#### Description

 show status of JuiceFS

-### Synopsis
+#### Synopsis

 ```
 juicefs status [command options] REDIS-URL
 ```

-### Options
+#### Options

 `--session value, -s value`\
 show detailed information (sustained inodes, locks) of the specified session (sid) (default: 0)

-## juicefs warmup
+### juicefs warmup

-### Description
+#### Description

 build cache for target directories/files

-### Synopsis
+#### Synopsis

 ```
 juicefs warmup [command options] [PATH ...]
 ```

-### Options
+#### Options

 `--file value, -f value`\
 file containing a list of paths
@@ -476,25 +510,25 @@ number of concurrent workers (default: 50)
 `--background, -b`\
 run in background (default: false)

-## juicefs dump
+### juicefs dump

-### Description
+#### Description

 dump metadata into a JSON file

-### Synopsis
+#### Synopsis

 ```
 juicefs dump [command options] META-ADDR FILE
 ```

-## juicefs load
+### juicefs load

-### Description
+#### Description

 load metadata from a previously dumped JSON file

-### Synopsis
+#### Synopsis

 ```
 juicefs load [command options] META-ADDR FILE

--- a/docs/zh_cn/command_reference.md
+++ b/docs/zh_cn/command_reference.md
@@ -4,9 +4,10 @@

 ## 概览

-在终端输入 `juicefs` 并执行，你就会看到所有可用的子命令。另外，你可以在每个子命令后面添加 `-h/--help` 标记获得该命令的详细帮助信息。
+在终端输入 `juicefs` 并执行，你就会看到所有可用的命令。另外，你可以在每个命令后面添加 `-h/--help` 标记获得该命令的详细帮助信息。

-```
+```bash
+$ juicefs -h
 NAME:
   juicefs - A POSIX file system built on Redis and object storage.

@@ -46,27 +47,60 @@ COPYRIGHT:
   AGPLv3
 ```

-用法：`juicefs [global options] command [command options] [arguments...]`
+**注意：**如果 `juicefs` 不在 `$PATH` 中，你需要指定程序所在的路径才能执行。例如，`juicefs` 如果在当前目录中，则可以使用 `./juicefs`。为了方便使用，建议将 `juicefs` 添加到  `$PATH` 中。可以参考 [快速上手指南](quick_start_guide.md) 了解安装相关内容。
+
+## 自动补全
+
+通过加载 `hack/autocomplete` 下的对应脚本可以启用命令的自动补全，例如：
+
+Bash:
+
+```bash
+$ source hack/autocomplete/bash_autocomplete
+```
+
+Zsh:
+
+```bash
+$ source hack/autocomplete/zsh_autocomplete
+```

-在所有命令后面添加 `-h` 或 `--help`，即可获得该命令的参数列表和帮助信息。
+请注意自动补全功能仅对当前会话有效。如果你希望对所有新会话都启用此功能，请将 `source` 命令添加到 `.bashrc` 或 `.zshrc` 中：
+
+```bash
+$ echo "source path/to/bash_autocomplete" >> ~/.bashrc
+```
+
+或
+
+```bash
+$ echo "source path/to/zsh_autocomplete" >> ~/.zshrc
+```
+
+另外，如果你是在 Linux 系统上使用 bash，也可以直接将脚本拷贝到 `/etc/bash_completion.d` 目录并将其重命名为 `juicefs`：
+
+```bash
+$ sudo cp hack/autocomplete/bash_autocomplete /etc/bash_completion.d/juicefs
+$ source /etc/bash_completion.d/juicefs
+```

-**注意**：如果 `juicefs` 不在 `$PATH` 中，你需要指定程序所在的路径才能执行。例如，`juicefs` 如果在当前目录中，则可以使用 `./juicefs`。为了方便使用，建议将 `juicefs` 添加到  `$PATH` 中。可以参考 [快速上手指南](quick_start_guide.md) 了解安装相关内容。
+**注意：**此特性基于 `github.com/urfave/cli/v2` 实现，更多信息请参见[这里](https://github.com/urfave/cli/blob/master/docs/v2/manual.md#enabling)。

-以下文档为您提供有关每个子命令的详细信息。
+## 命令列表

-## juicefs format
+### juicefs format

-### 描述
+#### 描述

 格式化文件系统；这是使用新文件系统的第一步。

-### 使用
+#### 使用

 ```
 juicefs format [command options] REDIS-URL NAME
 ```

-### 选项
+#### 选项

 `--block-size value`\
 块大小；单位为 KiB (默认: 4096)
@@ -104,19 +138,19 @@ RSA 私钥的路径 (PEM)
 `--no-update`\
 不要修改已有的格式化配置 (默认: false)

-## juicefs mount
+### juicefs mount

-### 描述
+#### 描述

 挂载一个已经格式化的文件系统。

-### 使用
+#### 使用

 ```
 juicefs mount [command options] REDIS-URL MOUNTPOINT
 ```

-### 选项
+#### 选项

 `--metrics value`\
 监控数据导出地址 (默认: "127.0.0.1:9567")
@@ -181,36 +215,36 @@ juicefs mount [command options] REDIS-URL MOUNTPOINT
 `--cache-partial-only`\
 仅缓存随机小块读 (默认: false)

-## juicefs umount
+### juicefs umount

-### 描述
+#### 描述

 卸载一个文件文件系统。

-### 使用
+#### 使用

 ```
 juicefs umount [command options] MOUNTPOINT
 ```

-### 选项
+#### 选项

 `-f, --force`\
 强制卸载一个忙碌的文件系统 (默认: false)

-## juicefs gateway
+### juicefs gateway

-### 描述
+#### 描述

 启动一个 S3 兼容的网关。

-### 使用
+#### 使用

 ```
 juicefs gateway [command options] REDIS-URL ADDRESS
 ```

-### 选项
+#### 选项

 `--get-timeout value`\
 下载一个对象的超时时间；单位为秒 (默认: 60)
@@ -254,19 +288,19 @@ juicefs gateway [command options] REDIS-URL ADDRESS
 `--no-banner`\
 禁用 MinIO 的启动信息 (默认: false)

-## juicefs sync
+### juicefs sync

-### 描述
+#### 描述

 在两个存储系统之间同步数据。

-### 使用
+#### 使用

 ```
 juicefs sync [command options] SRC DST
 ```

-### 选项
+#### 选项

 `--start KEY, -s KEY`\
 同步的第一个对象名
@@ -319,49 +353,49 @@ juicefs sync [command options] SRC DST
 `--no-https`\
 不要使用 HTTPS (默认: false)

-## juicefs rmr
+### juicefs rmr

-### 描述
+#### 描述

 递归删除指定目录下的所有文件。

-### 使用
+#### 使用

 ```
 juicefs rmr PATH ...
 ```

-## juicefs info
+### juicefs info

-### 描述
+#### 描述

 显示指定路径或 inode 的内部信息。

-### 使用
+#### 使用

 ```
 juicefs info [command options] PATH or INODE
 ```

-### 选项
+#### 选项

 `--inode, -i`\
 使用 inode 号而不是路径 (当前目录必须在 JuiceFS 挂载点内) (默认: false)


-## juicefs bench
+### juicefs bench

-### 描述
+#### 描述

 跑一轮基准性能测试，包括对大文件和小文件的读/写/获取属性操作。

-### 使用
+#### 使用

 ```
 juicefs bench [command options] PATH
 ```

-### 选项
+#### 选项

 `--block-size value`\
 块大小；单位为 MiB (默认: 1)
@@ -375,19 +409,19 @@ juicefs bench [command options] PATH
 `--small-file-count value`\
 小文件数量 (默认: 100)

-## juicefs gc
+### juicefs gc

-### 描述
+#### 描述

 收集泄漏的对象。

-### 使用
+#### 使用

 ```
 juicefs gc [command options] REDIS-URL
 ```

-### 选项
+#### 选项

 `--delete`\
 删除泄漏的对象 (默认: false)
@@ -398,31 +432,31 @@ juicefs gc [command options] REDIS-URL
 `--threads value`\
 用于删除泄漏对象的线程数 (默认: 10)

-## juicefs fsck
+### juicefs fsck

-### 描述
+#### 描述

 检查文件系统一致性。

-### 使用
+#### 使用

 ```
 juicefs fsck [command options] REDIS-URL
 ```

-## juicefs profile
+### juicefs profile

-### 描述
+#### 描述

 分析访问日志。

-### 使用
+#### 使用

 ```
 juicefs profile [command options] MOUNTPOINT/LOGFILE
 ```

-### 选项
+#### 选项

 `--uid value, -u value`\
 仅跟踪指定 UIDs (用逗号 , 分隔)
@@ -436,36 +470,36 @@ juicefs profile [command options] MOUNTPOINT/LOGFILE
 `--interval value`\
 显示间隔；单位为秒 (默认: 2)

-## juicefs status
+### juicefs status

-### 描述
+#### 描述

 显示 JuiceFS 的状态。

-### 使用
+#### 使用

 ```
 juicefs status [command options] REDIS-URL
 ```

-### 选项
+#### 选项

 `--session value, -s value`\
 展示指定会话 (sid) 的具体信息 (默认: 0)

-## juicefs warmup
+### juicefs warmup

-### 描述
+#### 描述

 主动为指定目录/文件建立缓存。

-### 使用
+#### 使用

 ```
 juicefs warmup [command options] [PATH ...]
 ```

-### 选项
+#### 选项

 `--file value, -f value`\
 指定一个包含一组路径的文件
@@ -476,25 +510,25 @@ juicefs warmup [command options] [PATH ...]
 `--background, -b`\
 后台运行 (默认: false)

-## juicefs dump
+### juicefs dump

-### 描述
+#### 描述

 将元数据导出到一个 JSON 文件中。

-### 使用
+#### 使用

 ```
 juicefs dump [command options] META-ADDR FILE
 ```

-## juicefs load
+### juicefs load

-### 描述
+#### 描述

 从之前导出的 JSON 文件中加载元数据。

-### 使用
+#### 使用

 ```
 juicefs load [command options] META-ADDR FILE

--- a/autocomplete/bash_autocomplete
+++ b/autocomplete/bash_autocomplete
--- a/autocomplete/zsh_autocomplete
+++ b/autocomplete/zsh_autocomplete