From e05c19d0ff37a900847a6073de0ca05498ebe6d1 Mon Sep 17 00:00:00 2001 From: ZhiHong Li Date: Sun, 1 May 2022 16:25:12 +0800 Subject: [PATCH] Add Chinese documentation translation & Fix spelling mistakes (#373) * Add Chinese documentation translation * Fix spelling mistakes --- README.md | 5 + docs/server.md | 2 +- docs/zh-CN/README.md | 195 ++++++++++++++++++++++++++++++++ docs/zh-CN/config.md | 137 ++++++++++++++++++++++ docs/zh-CN/import.md | 25 ++++ docs/zh-CN/key-binding.md | 37 ++++++ docs/zh-CN/list.md | 11 ++ docs/zh-CN/search.md | 37 ++++++ docs/zh-CN/server.md | 154 +++++++++++++++++++++++++ docs/zh-CN/shell-completions.md | 19 ++++ docs/zh-CN/stats.md | 35 ++++++ docs/zh-CN/sync.md | 51 +++++++++ 12 files changed, 707 insertions(+), 1 deletion(-) create mode 100644 docs/zh-CN/README.md create mode 100644 docs/zh-CN/config.md create mode 100644 docs/zh-CN/import.md create mode 100644 docs/zh-CN/key-binding.md create mode 100644 docs/zh-CN/list.md create mode 100644 docs/zh-CN/search.md create mode 100644 docs/zh-CN/server.md create mode 100644 docs/zh-CN/shell-completions.md create mode 100644 docs/zh-CN/stats.md create mode 100644 docs/zh-CN/sync.md diff --git a/README.md b/README.md index c6e7b9f..a3a065a 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ exit code, duration, time and command shown

+[English] | [简体中文] + Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands. Additionally, it provides optional and _fully encrypted_ synchronisation of your history between machines, via an Atuin @@ -195,3 +197,6 @@ to your `is-interactive` block in your `~/.config/fish/config.fish` file Atuin is named after "The Great A'Tuin", a giant turtle from Terry Pratchett's Discworld series of books. + +[English]: ./README.md +[简体中文]: ./docs/zh-CN/README.md \ No newline at end of file diff --git a/docs/server.md b/docs/server.md index 9c8c0c6..a50f187 100644 --- a/docs/server.md +++ b/docs/server.md @@ -51,7 +51,7 @@ Defaults to `127.0.0.1`. ### port -The post the atuin server should listen on. +The port the atuin server should listen on. Defaults to `8888`. diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md new file mode 100644 index 0000000..6156c7a --- /dev/null +++ b/docs/zh-CN/README.md @@ -0,0 +1,195 @@ +

+ Atuin +

+ +

+神奇的 shell 历史记录 +

+ +

+ + + + + +

+ +

+ animated +

+ +

+显示退出代码、命令持续时间、上次执行时间和执行的命令 +

+ +[English] | [简体中文] + +Atuin 使用 SQLite 数据库取代了你现有的 shell 历史，并为你的命令记录了额外的内容。此外，它还通过 Atuin 服务器，在机器之间提供可选的、完全加密的历史记录同步功能。 + + +除了搜索 UI，它还可以执行以下操作： + +``` +# 搜索昨天下午3点之后记录的所有成功的 `make` 命令 +atuin search --exit 0 --after "yesterday 3pm" make +``` + +你可以使用我(ellie)托管的服务器，也可以使用你自己的服务器！或者干脆不使用 sync 功能。所有的历史记录同步都是加密，即使我想，也无法访问你的数据。且我**真的**不想。 + +## 特点 + +- 重新绑定 `up` 和 `ctrl-r` 的全屏历史记录搜索UI界面 +- 使用 sqlite 数据库存储 shell 历史记录 +- 备份以及同步已加密的 shell 历史记录 +- 在不同的终端、不同的会话以及不同的机器上都有相同的历史记录 +- 记录退出代码、cwd、主机名、会话、命令持续时间，等等。 +- 计算统计数据，如 "最常用的命令"。 +- 不替换旧的历史文件 +- 通过 Alt-\ 快捷键快速跳转到之前的记录 +- 通过 ctrl-r 切换过滤模式;可以仅从当前会话、目录或全局来搜索历史记录 + +## 文档 + +- [快速开始](#快速开始) +- [安装](#安装) +- [导入](./import.md) +- [配置](./config.md) +- [历史记录搜索](./search.md) +- [历史记录云端同步](./sync.md) +- [历史记录统计](./stats.md) +- [运行你自己的服务器](./server.md) +- [键绑定](./key-binding.md) +- [shell补全](./shell-completions.md) + +## 支持的 Shells + +- zsh +- bas +- fish + +## 社区 + +Atuin 有一个 Discord 社区, 可以在 [这里](https://discord.gg/Fq8bJSKPHh) 获得 + +# 快速开始 + +## 使用默认的同步服务器 + +这将为您注册由我托管的默认同步服务器。 一切都是端到端加密的，所以你的秘密是安全的！ + +阅读下面的更多信息，了解仅供离线使用或托管您自己的服务器。 + +``` +bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) + +atuin register -u -e -p +atuin import auto +atuin sync +``` + +## 仅离线 (不同步) + +``` +bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) + +atuin import auto +``` + +## 安装 + +### 脚本 (推荐) + +安装脚本将帮助您完成设置，确保您的 shell 正确配置。 它还将使用以下方法之一，在可能的情况下首选系统包管理器（pacman、homebrew 等）。 + +``` +# 不要以root身份运行，如果需要的话，会要求root。 +bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) +``` + +### 使用cargo + +最好使用 [rustup](https://rustup.rs/) 来设置 Rust 工具链，然后你就可以运行下面的命令: + +``` +cargo install atuin +``` + +### Homebrew + +``` +brew install atuin +``` + +### MacPorts + +Atuin 也可以在 [MacPorts](https://ports.macports.org/port/atuin/) 中找到 + +``` +sudo port install atuin +``` + +### Pacman + +Atuin 在 Arch Linux 的 [社区存储库](https://archlinux.org/packages/community/x86_64/atuin/) 中可用。 + +``` +pacman -S atuin +``` + +### 从源码编译安装 + +``` +git clone https://github.com/ellie/atuin.git +cd atuin +cargo install --path . +``` + +## Shell 插件 + +安装二进制文件后，需要安装 shell 插件。 +如果你使用的是脚本安装，那么这一切应该都会帮您完成！ + +### zsh + +``` +echo 'eval "$(atuin init zsh)"' >> ~/.zshrc +``` + +或使用插件管理器: + +``` +zinit load ellie/atuin +``` + +### bash + +我们需要设置一些钩子(hooks), 所以首先需要安装 bash-preexec : + +``` +curl https://raw.githubusercontent.com/rcaloras/bash-preexec/master/bash-preexec.sh -o ~/.bash-preexec.sh +echo '[[ -f ~/.bash-preexec.sh ]] && source ~/.bash-preexec.sh' >> ~/.bashrc +``` + +然后设置Atuin + +``` +echo 'eval "$(atuin init bash)"' >> ~/.bashrc +``` + +### fish + +添加 + +``` +atuin init fish | source +``` + +到 ~/.config/fish/config.fish 文件中的 is-interactive 块中 + +## ...这个名字是什么意思? + +Atuin 以 "The Great A'Tuin" 命名, 这是一只来自 Terry Pratchett 的 Discworld 系列书籍的巨龟。 + + +[English]: ../../README.md +[简体中文]: ./README.md \ No newline at end of file diff --git a/docs/zh-CN/config.md b/docs/zh-CN/config.md new file mode 100644 index 0000000..a94b961 --- /dev/null +++ b/docs/zh-CN/config.md @@ -0,0 +1,137 @@ +# 配置 + +Atuin 维护两个配置文件，存储在 `~/.config/atuin/` 中。 我们将数据存储在 `~/.local/share/atuin` 中（除非被 XDG\_\* 覆盖）。 + +您可以通过设置更改配置目录的路径 `ATUIN_CONFIG_DIR`。 例如 + +``` +export ATUIN_CONFIG_DIR = /home/ellie/.atuin +``` + +## 客户端配置 + +``` +~/.config/atuin/config.toml +``` + +客户端运行在用户的机器上，除非你运行的是服务器，否则这就是你所关心的。 + +见 [config.toml](../../atuin-client/config.toml) 中的例子 + +### `dialect` + +这配置了 [stats](stats.md) 命令解析日期的方式。 它有两个可能的值 + +``` +dialect = "uk" +``` + +或者 + +``` +dialect = "us" +``` + +默认为 "us". + +### `auto_sync` + +配置登录时是否自动同步。默认为 true + +``` +auto_sync = true/false +``` + +### `sync_address` + +同步的服务器地址！ 默认为 `https://api.atuin.sh` + +``` +sync_address = "https://api.atuin.sh" +``` + +### `sync_frequency` + +多长时间与服务器自动同步一次。这可以用一种"人类可读"的格式给出。例如，`10s`，`20m`，`1h`，等等。默认为 `1h` 。 + +如果设置为 `0`，Atuin将在每个命令之后进行同步。一些服务器可能有潜在的速率限制，这不会造成任何问题。 + +``` +sync_frequency = "1h" +``` + +### `db_path` + +Atuin SQlite数据库的路径。默认为 +`~/.local/share/atuin/history.db` + +``` +db_path = "~/.history.db" +``` + +### `key_path` + +Atuin加密密钥的路径。默认为 +`~/.local/share/atuin/key` + +``` +key = "~/.atuin-key" +``` + +### `session_path` + +Atuin服务器会话文件的路径。默认为 +`~/.local/share/atuin/session` 。 这本质上只是一个API令牌 + +``` +key = "~/.atuin-session" +``` + +### `search_mode` + +使用哪种搜索模式。Atuin 支持 "prefix"（前缀）、"fulltext"（全文） 和 "fuzzy"（模糊）搜索模式。前缀(prefix)搜索语法为 "query\*"，全文(full text)搜索语法为 "\*query\*"，而模糊搜索适用的搜索语法 [如下所述](#fuzzy-search-syntax) 。 + +默认配置为 "prefix" + +### `filter_mode` + +搜索时要使用的默认过滤器 + +| 模式 | 描述 | +|--------------- | --------------- | +| global (default) | 从所有主机、所有会话、所有目录中搜索历史记录 | +| host | 仅从该主机搜索历史记录 | +| session | 仅从当前会话中搜索历史记录 | +| directory | 仅从当前目录搜索历史记录| + +过滤模式仍然可以通过 ctrl-r 来切换 + + +``` +search_mode = "fulltext" +``` + +#### `fuzzy` 的搜索语法 + +`fuzzy` 搜索语法的基础是 [fzf 搜索语法](https://github.com/junegunn/fzf#search-syntax) 。 + +| 内容 | 匹配类型 | 描述 | +| --------- | -------------------------- | ------------------------------------ | +| `sbtrkt` | fuzzy-match | 匹配 `sbtrkt` 的项目 | +| `'wild` | exact-match (quoted) | 包含 `wild` 的项目 | +| `^music` | prefix-exact-match | 以 `music` 开头的项目 | +| `.mp3$` | suffix-exact-match | 以 `.mp3` 结尾的项目 | +| `!fire` | inverse-exact-match | 不包括 `fire` 的项目 | +| `!^music` | inverse-prefix-exact-match | 不以 `music` 开头的项目 | +| `!.mp3$` | inverse-suffix-exact-match | 不以 `.mp3` 结尾的项目 | + + +单个条形字符术语充当 OR 运算符。 例如，以下查询匹配以 `core` 开头并以 `go`、`rb` 或 `py` 结尾的条目。 + +``` +^core go$ | rb$ | py$ +``` + +## 服务端配置 + +`// TODO` diff --git a/docs/zh-CN/import.md b/docs/zh-CN/import.md new file mode 100644 index 0000000..c1f1d06 --- /dev/null +++ b/docs/zh-CN/import.md @@ -0,0 +1,25 @@ +# `atuin import` + +Atuin 可以从您的“旧”历史文件中导入您的历史记录 + +`atuin import auto` 将尝试找出你的 shell（通过 \$SHELL）并运行正确的导入器 + +不幸的是，这些旧文件没有像 Atuin 那样存储尽可能多的信息，因此并非所有功能都可用于导入的数据。 + +# zsh + +``` +atuin import zsh +``` + +如果你设置了 HISTFILE，这应该会被选中！如果没有，可以尝试以下操作 + +``` +HISTFILE=/path/to/history/file atuin import zsh +``` + +这支持简单和扩展形式 + +# bash + +TODO diff --git a/docs/zh-CN/key-binding.md b/docs/zh-CN/key-binding.md new file mode 100644 index 0000000..ea93032 --- /dev/null +++ b/docs/zh-CN/key-binding.md @@ -0,0 +1,37 @@ +# 键绑定 + +默认情况下， Atuin 将会重新绑定 Ctrl-r 和 `up` 键。如果你不想使用默认绑定，请在调用 `atuin init` 之前设置 ATUIN_NOBIND + +例如： + +``` +export ATUIN_NOBIND="true" +eval "$(atuin init zsh)" +``` + +如果需要，你可以在调用 `atuin init` 之后对 Atuin 重新进行键绑定 + +# zsh + +Atuin 定义了 ZLE 部件 "\_atuin_search_widget" + +``` +export ATUIN_NOBIND="true" +eval "$(atuin init zsh)" + +bindkey '^r' _atuin_search_widget + +# 取决于终端模式 +bindkey '^[[A' _atuin_search_widget +bindkey '^[OA' _atuin_search_widget +``` + +# bash + +``` +export ATUIN_NOBIND="true" +eval "$(atuin init bash)" + +# 绑定到 ctrl-r, 也可以在这里添加任何其他你想要的绑定方式 +bind -x '"\C-r": __atuin_history' +``` diff --git a/docs/zh-CN/list.md b/docs/zh-CN/list.md new file mode 100644 index 0000000..c341ec4 --- /dev/null +++ b/docs/zh-CN/list.md @@ -0,0 +1,11 @@ +# 历史记录列表 + +``` +atuin history list +``` + +| 参数 | 描述 | +| -------------- | ----------------------------------------------------------------------------- | +| `--cwd/-c` | 要列出历史记录的目录（默认：所有目录） | +| `--session/-s` | 只对当前会话启用列表历史（默认：false） | +| `--human/-h` | 对时间戳和持续时间使用人类可读的格式（默认：false）。 | diff --git a/docs/zh-CN/search.md b/docs/zh-CN/search.md new file mode 100644 index 0000000..b99233c --- /dev/null +++ b/docs/zh-CN/search.md @@ -0,0 +1,37 @@ +# `atuin search` + +``` +atuin search +``` + +Atuin 搜索还支持带有 `*` 或 `%` 字符的通配符。 默认情况下，会执行前缀搜索（即，所有查询都会自动附加通配符）。 + +| 参数 | 描述 | +| ------------------ | ----------------------------------------------------------------------------- | +| `--cwd/-c` | 列出历史记录的目录（默认：所有目录） | +| `--exclude-cwd` | 不包括在此目录中运行的命令（默认值：none） | +| `--exit/-e` | 按退出代码过滤（默认：none） | +| `--exclude-exit` | 不包括以该值退出的命令（默认值：none） | +| `--before` | 仅包括在此时间之前运行的命令（默认值：none） | +| `--after` | 仅包含在此时间之后运行的命令（默认值：none） | +| `--interactive/-i` | 打开交互式搜索 UI（默认值：false） | +| `--human/-h` | 对时间戳和持续时间使用人类可读的格式（默认值：false） | + +## 举例 + +``` +# 打开交互式搜索 TUI +atuin search -i + +# 打开预装了查询的交互式搜索 TUI +atuin search -i atuin + +# 搜索所有以 cargo 开头且成功退出的命令。 +atuin search --exit 0 cargo + +# 从当前目录中搜索所有在2021年4月1日之前运行且失败的命令。 +atuin search --exclude-exit 0 --before 01/04/2021 --cwd . + +#搜索所有以 cargo 开头，成功退出且是在昨天下午3点之后运行的命令。 +atuin search --exit 0 --after "yesterday 3pm" cargo +``` diff --git a/docs/zh-CN/server.md b/docs/zh-CN/server.md new file mode 100644 index 0000000..534cb67 --- /dev/null +++ b/docs/zh-CN/server.md @@ -0,0 +1,154 @@ +# `atuin server` + +Atuin 允许您运行自己的同步服务器，以防您不想使用我(ellie)托管的服务器 :) + +目前只有一个子命令，`atuin server start`，它将启动 Atuin http 同步服务器。 + +``` +USAGE: + atuin server start [OPTIONS] + +FLAGS: + --help Prints help information + -V, --version Prints version information + +OPTIONS: + -h, --host + -p, --port +``` + +## 配置 + +服务器的配置与客户端的配置是分开的，即使它们是相同的二进制文件。服务器配置可以在 `~/.config/atuin/server.toml` 找到。 + +它看起来像这样: + +```toml +host = "0.0.0.0" +port = 8888 +open_registration = true +db_uri="postgres://user:password@hostname/database" +``` + +另外，配置也可以用环境变量来提供。 + +```sh +ATUIN_HOST="0.0.0.0" +ATUIN_PORT=8888 +ATUIN_OPEN_REGISTRATION=true +ATUIN_DB_URI="postgres://user:password@hostname/database" +``` + +### host + +Atuin 服务器应该监听的地址 + +默认为 `127.0.0.1`. + +### port + +Atuin 服务器应该监听的端口 + +默认为 `8888`. + +### open_registration + +如果为 `true` ，atuin 将接受新用户注册。如果您不希望其他人能够使用您的服务器，请在创建自己的账号后将此设置为 `false` + +默认为 `false`. + +### db_uri + +一个有效的 postgres URI, 用户和历史记录数据将被保存到其中。 + +## Docker + +提供了一个 docker 镜像（image），可以更轻松地将服务器部署为容器（container）。 + +```sh +docker run -d -v "$USER/.config/atuin:/config" ghcr.io/ellie/atuin:latest server start +``` + +## Docker Compose + +使用已有的 docker 镜像（image）来托管你自己的 Atuin，可以使用提供的 docker-compose 文件来完成 + +在 `docker-compose.yml` 同级目录下创建一个 `.env` 文件，内容如下: + +``` +ATUIN_DB_USERNAME=atuin +# Choose your own secure password +ATUIN_DB_PASSWORD=really-insecure +``` + +创建一个 `docker-compose.yml` 文件: + +```yaml +version: '3.5' +services: + atuin: + restart: always + image: ghcr.io/ellie/atuin:main + command: server start + volumes: + - "./config:/config" + links: + - postgresql:db + ports: + - 8888:8888 + environment: + ATUIN_HOST: "0.0.0.0" + ATUIN_OPEN_REGISTRATION: "true" + ATUIN_DB_URI: postgres://$ATUIN_DB_USERNAME:$ATUIN_DB_PASSWORD@db/atuin + postgresql: + image: postgres:14 + restart: unless-stopped + volumes: # 不要删除索引数据库文件的永久存储空间! + - "./database:/var/lib/postgresql/data/" + environment: + POSTGRES_USER: $ATUIN_DB_USERNAME + POSTGRES_PASSWORD: $ATUIN_DB_PASSWORD + POSTGRES_DB: atuin +``` + +使用 `docker-compose` 启动服务: + +```sh +docker-compose up -d +``` + +### 使用 systemd 来管理你的 Atuin 服务器 + +以下 `systemd` 单元文件用于管理您的 `docker-compose` 托管服务： + +``` +[Unit] +Description=Docker Compose Atuin Service +Requires=docker.service +After=docker.service + +[Service] +# docker-compose 文件所在的位置 +WorkingDirectory=/srv/atuin-server +ExecStart=/usr/bin/docker-compose up +ExecStop=/usr/bin/docker-compose down +TimeoutStartSec=0 +Restart=on-failure +StartLimitBurst=3 + +[Install] +WantedBy=multi-user.target +``` + +使用以下命令启动并启用服务： + +```sh +systemctl enable --now atuin +``` + +检查它是否运行： + +```sh +systemctl status atuin +``` + diff --git a/docs/zh-CN/shell-completions.md b/docs/zh-CN/shell-completions.md new file mode 100644 index 0000000..0979dcb --- /dev/null +++ b/docs/zh-CN/shell-completions.md @@ -0,0 +1,19 @@ +# `atuin gen-completions` + +Atuin 的 [Shell 补全](https://en.wikipedia.org/wiki/Command-line_completion) 可以通过 `gen-completions` 子命令指定输出目录和所需的 shell 来生成。 + +``` +$ atuin gen-completions --shell bash --out-dir $HOME + +Shell completion for BASH is generated in "/home/user" +``` + +`--shell` 参数的可能值如下： + +- `bash` +- `fish` +- `zsh` +- `powershell` +- `elvish` + +此外, 请参阅 [支持的 Shells](./README.md#支持的-Shells). diff --git a/docs/zh-CN/stats.md b/docs/zh-CN/stats.md new file mode 100644 index 0000000..2bf557b --- /dev/null +++ b/docs/zh-CN/stats.md @@ -0,0 +1,35 @@ +# `atuin stats` + +Atuin 还可以根据你的历史记录进行计算统计数据 - 目前这只是一个小的基本功能，但更多功能即将推出 + +``` +$ atuin stats day last friday + ++---------------------+------------+ +| Statistic | Value | ++---------------------+------------+ +| Most used command | git status | ++---------------------+------------+ +| Commands ran | 450 | ++---------------------+------------+ +| Unique commands ran | 213 | ++---------------------+------------+ + +$ atuin stats day 01/01/21 # 也接受绝对日期 +``` + +它还可以计算所有已知历史记录的统计数据。 + +``` +$ atuin stats all + ++---------------------+-------+ +| Statistic | Value | ++---------------------+-------+ +| Most used command | ls | ++---------------------+-------+ +| Commands ran | 8190 | ++---------------------+-------+ +| Unique commands ran | 2996 | ++---------------------+-------+ +``` diff --git a/docs/zh-CN/sync.md b/docs/zh-CN/sync.md new file mode 100644 index 0000000..8250a27 --- /dev/null +++ b/docs/zh-CN/sync.md @@ -0,0 +1,51 @@ +# `atuin sync` + +Atuin 可以将您的历史记录备份到服务器，并使用它来确保多台机器具有相同的 shell 历史记录。 这都是端到端加密的，因此服务器操作员_永远_看不到您的数据！ + +任何人都可以托管一个服务器（尝试 `atuin server start`，更多文档将在后面介绍），但我(ellie)在 https://api.atuin.sh 上托管了一个。这是默认的服务器地址，可以在 [配置](config.md) 中更改。 同样，我_不能_看到您的数据，也不想。 + +## 同步频率 + +除非另有配置，否则同步将自动执行。同步的频率可在 [配置](config.md) 中配置。 + +## 同步 + +你可以通过 `atuin sync` 来手动触发同步 + +## 注册 + +注册一个同步账号 + +``` +atuin register -u -e -p +``` + +用户名（USERNAME）必须是唯一的，电子邮件（EMAIL）仅用于重要通知（安全漏洞、服务更改等） + +注册后，意味着你也已经登录了 :) 同步应该从这里自动发生！ + +## 密钥 + +由于你的数据是加密的， Atuin 将为你生成一个密钥。它被存储在 Atuin 的数据目录里（ Linus 上为 `~/.local/share/atuin`） + +你也可以通过以下方式获得它 + +``` +atuin key +``` + +千万不要跟任何人分享这个！ + +## 登录 + +如果你想登录到一个新的机器上，你需要你的加密密钥（`atuin key`）。 + +``` +atuin login -u -p -k +``` + +## 登出 + +``` +atuin logout +```