From 2d95227c717d6d0553ba3fbca0ea2ae8a77a20f8 Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:22:17 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 196 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 101 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index c9319dc..ff3cbd7 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,34 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/kashav/fsql) · [上游 README](https://github.com/kashav/fsql/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # fsql [![Go](https://github.com/kashav/fsql/actions/workflows/go.yml/badge.svg)](https://github.com/kashav/fsql/actions/workflows/go.yml) ->Search through your filesystem with SQL-esque queries. +>使用类 SQL 查询在你的文件系统中进行搜索。 -## Contents +## 目录 -- [Demo](#demo) -- [Installation](#installation) -- [Usage](#usage) -- [Query Syntax](#query-syntax) -- [Examples](#usage-examples) -- [Contribute](#contribute) -- [License](#license) +- [演示](#demo) +- [安装](#installation) +- [用法](#usage) +- [查询语法](#query-syntax) +- [示例](#usage-examples) +- [贡献](#contribute) +- [许可证](#license) -## Demo +## 演示 [![fsql.gif](./media/fsql.gif)](https://asciinema.org/a/120534) -## Installation +## 安装 -#### Binaries +#### 二进制文件 -[View latest release](https://github.com/kashav/fsql/releases/latest). +[查看最新发布版本](https://github.com/kashav/fsql/releases/latest). -#### Via Go +#### 通过 Go 安装 ```sh $ go get -u -v github.com/kashav/fsql/... @@ -30,7 +36,7 @@ $ which fsql $GOPATH/bin/fsql ``` -#### Via Homebrew +#### 通过 Homebrew 安装 ```sh $ brew install fsql @@ -38,7 +44,7 @@ $ which fsql /usr/local/bin/fsql ``` -#### Build manually +#### 手动构建 ```sh $ git clone https://github.com/kashav/fsql.git $GOPATH/src/github.com/kashav/fsql @@ -47,11 +53,11 @@ $ make $ ./fsql ``` -## Usage +## 用法 -fsql expects a single query via stdin. You may also choose to use fsql in interactive mode. +fsql 期望通过 stdin 接收单个查询。你也可以选择以交互模式使用 fsql。 -View the usage dialogue with the `-help` flag. +使用 `-help` 标志查看用法说明。 ```sh $ fsql -help @@ -61,27 +67,27 @@ usage: fsql [options] [query] print version and exit ``` -## Query syntax +## 查询语法 -In general, each query requires a `SELECT` clause (to specify which attributes will be shown), a `FROM` clause (to specify which directories to search), and a `WHERE` clause (to specify conditions to test against). +一般来说，每条查询都需要一个 `SELECT` 子句（用于指定要显示哪些属性）、一个 `FROM` 子句（用于指定要搜索哪些目录）和一个 `WHERE` 子句（用于指定要测试的条件）。 ```console >>> SELECT attribute, ... FROM source, ... WHERE condition; ``` -You may choose to omit the `SELECT` and `WHERE` clause. +你可以选择省略 `SELECT` 和 `WHERE` 子句。 -If you're providing your query via stdin, quotes are **not** required, however you'll have to escape _reserved_ characters (e.g. `*`, `<`, `>`, etc). +如果你通过 stdin 提供查询，则**不**需要引号，但你必须转义*保留*字符（例如 `*`、`<`、`>` 等）。 -### Attribute +### 属性 -Currently supported attributes include `name`, `size`, `time`, `hash`, `mode`. +当前支持的属性包括 `name`、`size`、`time`、`hash`、`mode`。 -Use `all` or `*` to choose all; if no attribute is provided, this is chosen by default. +使用 `all` 或 `*` 来选择全部；如果未提供属性，则默认选择此项。 -**Examples**: +**示例**： -Each group features a set of equivalent clauses. +每组都包含一组等效的子句。 ```console >>> SELECT name, size, time ... @@ -94,19 +100,19 @@ Each group features a set of equivalent clauses. >>> FROM ... ``` -### Source +### 源 -Each source should be a relative or absolute path to a directory on your machine. +每个源都应是计算机上某个目录的相对或绝对路径。 -Source paths may include environment variables (e.g. `$GOPATH`) or tildes (`~`). Use a hyphen (`-`) to exclude a directory. Source paths also support usage of [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)). +源路径可以包含环境变量（例如 `$GOPATH`）或波浪号（`~`）。使用连字符（`-`）来排除目录。源路径还支持使用 [glob 模式](https://en.wikipedia.org/wiki/Glob_(programming)). -In the case that a directory begins with a hyphen (e.g. `-foo`), use the following to include it as a source: +如果某个目录以连字符开头（例如 `-foo`），请使用以下方式将其包含为源： ```console >>> ... FROM ./-foo ... ``` -**Examples**: +**示例**： ```console >>> ... FROM . ... @@ -120,62 +126,62 @@ In the case that a directory begins with a hyphen (e.g. `-foo`), use the followi >>> ... FROM $GOPATH, -.git/ ... ``` -### Condition +### 条件 -#### Condition syntax +#### 条件语法 -A single condition is made up of 3 parts: an attribute, an operator, and a value. +单个条件由 3 部分组成：属性、运算符和值。 -- **Attribute**: +- **属性**： - A valid attribute is any of the following: `name`, `size`, `mode`, `time`. + 有效属性是以下任意一项：`name`、`size`、`mode`、`time`。 -- **Operator**: +- **运算符**： - Each attribute has a set of associated operators. + 每个属性都有一组关联的运算符。 - - `name`: + - `name`： - | Operator | Description | + | 运算符 | 说明 | | :---: | --- | - | `=` | String equality | - | `<>` / `!=` | Synonymous to using `"NOT ... = ..."` | - | `IN` | Basic list inclusion | - | `LIKE` | Simple pattern matching. Use `%` to match zero, one, or multiple characters. Check that a string begins with a value: `%`, ends with a value: `%`, or contains a value: `%%`. | - | `RLIKE` | Pattern matching with regular expressions. | + | `=` | 字符串相等 | + | `<>` / `!=` | 与使用 `"NOT ... = ..."` 同义 | + | `IN` | 基本列表包含 | + | `LIKE` | 简单模式匹配。使用 `%` 匹配零个、一个或多个字符。检查字符串是否以某值开头：`%`，以某值结尾：`%`，或包含某值：`%%`。 | + | `RLIKE` | 使用正则表达式进行模式匹配。 | - - `size` / `time`: + - `size` / `time`： - - All basic algebraic operators: `>`, `>=`, `<`, `<=`, `=`, and `<>` / `!=`. + - 所有基本代数运算符：`>`、`>=`、`<`、`<=`、`=`，以及 `<>` / `!=`。 - - `hash`: + - `hash`： - - `=` or `<>` / `!=` + - `=` 或 `<>` / `!=` - - `mode`: + - `mode`： - `IS` -- **Value**: +- **值**： - If the value contains spaces, wrap the value in quotes (either single or double) or backticks. + 如果值包含空格，请用引号（单引号或双引号）或反引号将值括起来。 - The default unit for `size` is bytes. + `size` 的默认单位是字节。 - The default format for `time` is `MMM DD YYYY HH MM` (e.g. `"Jan 02 2006 15 04"`). + `time` 的默认格式是 `MMM DD YYYY HH MM`（例如 `"Jan 02 2006 15 04"`）。 - Use `mode` to test if a file is regular (`IS REG`) or if it's a directory (`IS DIR`). + 使用 `mode` 来测试文件是否为普通文件（`IS REG`），或是否为目录（`IS DIR`）。 - Use `hash` to compute and/or compare the hash value of a file. The default algorithm is `SHA1` + 使用 `hash` 来计算和/或比较文件的哈希值。默认算法是 `SHA1` -#### Conjunction / Disjunction +#### 合取 / 析取 -Use `AND` / `OR` to join conditions. Note that precedence is assigned based on order of appearance. +使用 `AND` / `OR` 来连接条件。请注意，优先级按出现顺序分配。 -This means `WHERE a AND b OR c` is **not** the same as `WHERE c OR b AND a`. Use parentheses to get around this behaviour, i.e. `WHERE a AND b OR c` **is** the same as `WHERE c OR (b AND a)`. +这意味着 `WHERE a AND b OR c` **不**等同于 `WHERE c OR b AND a`。使用括号来规避这一行为，即 `WHERE a AND b OR c` **等同**于 `WHERE c OR (b AND a)`。 -**Examples**: +**示例**： ```console >>> ... WHERE name = main.go OR size = 5 ... @@ -185,48 +191,48 @@ This means `WHERE a AND b OR c` is **not** the same as `WHERE c OR b AND a`. Use >>> ... WHERE name = main.go AND size > 20 ... ``` -#### Negation +#### 否定 -Use `NOT` to negate a condition. This keyword **must** precede the condition (e.g. `... WHERE NOT a ...`). +使用 `NOT` 来否定条件。此关键字**必须**位于条件之前（例如 `... WHERE NOT a ...`）。 -Note that negating parenthesized conditions is currently not supported. However, this can easily be resolved by applying [De Morgan's laws](https://en.wikipedia.org/wiki/De_Morgan%27s_laws) to your query. For example, `... WHERE NOT (a AND b) ...` is _logically equivalent_ to `... WHERE NOT a OR NOT b ...` (the latter is actually more optimal, due to [lazy evaluation](https://en.wikipedia.org/wiki/Lazy_evaluation)). +请注意，当前不支持对括号括起的条件进行否定。不过，你可以通过对查询应用 [德摩根定律（De Morgan's laws）](https://en.wikipedia.org/wiki/De_Morgan%27s_laws) 来轻松解决这一问题。例如，`... WHERE NOT (a AND b) ...` 在*逻辑上*等同于 `... WHERE NOT a OR NOT b ...`（由于 [惰性求值（lazy evaluation）](https://en.wikipedia.org/wiki/Lazy_evaluation)).，后者实际上更优）。 -**Examples**: +**示例**： ```console >>> ... WHERE NOT name = main.go ... ``` -### Attribute Modifiers +### 属性修饰符 -Attribute modifiers are used to specify how input and output values should be processed. These functions are applied directly to attributes in the `SELECT` and `WHERE` clauses. +属性修饰符用于指定输入和输出值应如何处理。这些函数直接应用于 `SELECT` 和 `WHERE` 子句中的属性。 -The table below lists currently-supported modifiers. Note that the first parameter to `FORMAT` is always the attribute name. +下表列出了当前支持的修饰符。请注意，`FORMAT` 的第一个参数始终是属性名称。 -| Attribute | Modifier | Supported in `SELECT` | Supported in `WHERE` | +| 属性 | 修饰符 | 支持于 `SELECT` | 支持于 `WHERE` | | :---: | --- | :---: | :---: | | `hash` | `SHA1(, n)` | ✔️ | ✔️ | -| `name` | `UPPER` (synonymous to `FORMAT(, UPPER)`) | ✔️ | ✔️ | -| | `LOWER` (synonymous to `FORMAT(, LOWER)`) | ✔️ | ✔️ | +| `name` | `UPPER`（与 `FORMAT(, UPPER)` 同义） | ✔️ | ✔️ | +| | `LOWER`（与 `FORMAT(, LOWER)` 同义） | ✔️ | ✔️ | | | `FULLPATH` | ✔️ | | | | `SHORTPATH` | ✔️ | | | `size` | `FORMAT(, unit)` | ✔️ | ✔️ | | `time` | `FORMAT(, layout)` | ✔️ | ✔️ | -- **`n`**: +- **`n`**： - Specify the length of the hash value. Use a negative integer or `ALL` to display all digits. + 指定哈希值的长度。使用负整数或 `ALL` 来显示所有数字。 -- **`unit`**: +- **`unit`**： - Specify the size unit. One of: `B` (byte), `KB` (kilobyte), `MB` (megabyte), or `GB` (gigabyte). + 指定大小单位。可选：`B`（字节）、`KB`（千字节）、`MB`（兆字节）或 `GB`（千兆字节）。 -- **`layout`**: +- **`layout`**： - Specify the time layout. One of: [`ISO`](https://en.wikipedia.org/wiki/ISO_8601), [`UNIX`](https://en.wikipedia.org/wiki/Unix_time), or [custom](https://golang.org/pkg/time/#Time.Format). Custom layouts must be provided in reference to the following date: `Mon Jan 2 15:04:05 -0700 MST 2006`. + 指定时间布局。可选：[`ISO`](https://en.wikipedia.org/wiki/ISO_8601),、[`UNIX`](https://en.wikipedia.org/wiki/Unix_time), 或 [自定义（custom）](https://golang.org/pkg/time/#Time.Format). 自定义布局必须参照以下日期提供：`Mon Jan 2 15:04:05 -0700 MST 2006`。 -**Examples**: +**示例**： ```console >>> SELECT SHA1(hash, 20) ... @@ -244,33 +250,33 @@ The table below lists currently-supported modifiers. Note that the first paramet >>> ... WHERE FORMAT(time, "Mon Jan 2 2006 15:04:05") ... ``` -### Subqueries +### 子查询 -Subqueries allow for more complex condition statements. These queries are recursively evaluated while parsing. SELECTing multiple attributes in a subquery is not currently supported; if more than one attribute (or `all`) is provided, only the first attribute is used. +子查询允许编写更复杂的条件语句。这些查询在解析时会被递归求值。当前不支持在子查询中 SELECT 多个属性；如果提供了多个属性（或 `all`），则只会使用第一个属性。 -Support for referencing superqueries is not yet implemented, see [#4](https://github.com/kashav/fsql/issues/4) if you'd like to help with this. +引用外层查询的功能尚未实现，如果你想为此提供帮助，请参阅 [#4](https://github.com/kashav/fsql/issues/4)。 -**Examples**: +**示例**： ```console >>> ... WHERE name IN (SELECT name FROM ../foo) ... ``` -## Usage Examples +## 用法示例 -List all attributes of each directory in your home directory (note the escaped `*`): +列出主目录中每个目录的所有属性（请注意转义的 `*`）： ```console $ fsql SELECT \* FROM ~ WHERE mode IS DIR ``` -List the names of all files in the Desktop and Downloads directory that contain `csc` in the name: +列出 Desktop 和 Downloads 目录中名称包含 `csc` 的所有文件的名称： ```console $ fsql "SELECT name FROM ~/Desktop, ~/Downloads WHERE name LIKE %csc%" ``` -List all files in the current directory that are also present in some other directory: +列出当前目录中也存在于其他某个目录中的所有文件： ```console $ fsql @@ -279,9 +285,9 @@ $ fsql ... ); ``` -Passing queries via stdin without quotes is a bit of a pain, hopefully the next examples highlight that, my suggestion is to use interactive mode or wrap the query in quotes if you're doing anything with subqueries or attribute modifiers. +通过 stdin 传递不带引号的查询有点麻烦，希望接下来的示例能说明这一点，我的建议是：如果你要使用子查询或属性修饰符，请使用交互模式，或将查询用引号括起来。 -List all files named `main.go` in `$GOPATH` which are larger than 10.5 kilobytes or smaller than 100 bytes: +列出 `$GOPATH` 中名为 `main.go`、大于 10.5 千字节或小于 100 字节的所有文件： ```console $ fsql SELECT all FROM $GOPATH WHERE name = main.go AND \(FORMAT\(size, KB\) \>= 10.5 OR size \< 100\) @@ -300,7 +306,7 @@ $ fsql ... ; ``` -List the name, size, and modification time of JavaScript files in the current directory that were modified after April 1st 2017: +列出当前目录中在 2017 年 4 月 1 日之后修改过的 JavaScript 文件的名称、大小和修改时间： ```console $ fsql SELECT UPPER\(name\), FORMAT\(size, KB\), FORMAT\(time, ISO\) FROM . WHERE name LIKE %.js AND time \> \'Apr 01 2017 00 00\' @@ -318,11 +324,11 @@ $ fsql ... ; ``` -## Contribute +## 贡献 -This project is completely open source, feel free to [open an issue](https://github.com/kashav/fsql/issues) or [submit a pull request](https://github.com/kashav/fsql/pulls). +本项目完全开源，欢迎[提交 Issue](https://github.com/kashav/fsql/issues) 或[发起 Pull Request（拉取请求）](https://github.com/kashav/fsql/pulls). -Before submitting code, please ensure that tests are passing and the linter is happy. The following commands may be of use, refer to the [Makefile](./Makefile) to see what they do. +提交代码前，请确保测试通过且 linter 检查无问题。以下命令可能对你有所帮助，请参阅 [Makefile](./Makefile) 了解它们的作用。 ```sh $ make install \ @@ -336,6 +342,6 @@ $ make bootstrap-dist \ dist ``` -## License +## 许可证 -fsql source code is available under the [MIT license](./LICENSE). +fsql 源代码遵循 [MIT 许可证](./LICENSE) 发布。