wehub/kashav--fsql
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:22:17 +00:00
parent 4cb763a556
commit 2d95227c71
1 changed files with 101 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+101 -95
View File
@@ -1,28 +1,34 @@
<!-- WEHUB_ZH_README -->
> [!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: `<value>%`, ends with a value: `%<value>`, or contains a value: `%<value>%`. |
| `RLIKE` | Pattern matching with regular expressions. |
| `=` | 字符串相等 |
| `<>` / `!=` | 与使用 `"NOT ... = ..."` 同义 |
| `IN` | 基本列表包含 |
| `LIKE` | 简单模式匹配。使用 `%` 匹配零个、一个或多个字符。检查字符串是否以某值开头：`<value>%`，以某值结尾：`%<value>`，或包含某值：`%<value>%`。 |
| `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) 发布。