Skip to content

Commit 69eb92a

Browse files
Zettat123Zettat123
authored
zh-cn translation for usage docs (#24897)
1 parent 9858d3b commit 69eb92a

14 files changed

+988
-6
lines changed

‎docs/content/doc/usage/agit-support.zh-cn.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
date: "2023-05-23T09:00:00+08:00"
3+
title: "Agit 设置"
4+
slug: "agit-setup"
5+
weight: 12
6+
toc: false
7+
draft: false
8+
aliases:
9+
- /zh-cn/agit-setup
10+
menu:
11+
sidebar:
12+
parent: "usage"
13+
name: "Agit 设置"
14+
weight: 12
15+
identifier: "agit-setup"
16+
---
17+
18+
# Agit 设置
19+
20+
在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。
21+
22+
## 使用 Agit 创建 PR
23+
24+
Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。
25+
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
26+
下面的示例说明了这一点：
27+
28+
```shell
29+
git push origin HEAD:refs/for/master
30+
```
31+
32+
该命令的结构如下：
33+
34+
- `HEAD`：目标分支
35+
- `refs/<for|draft|for-review>/<branch>`：目标 PR 类型
36+
- `for`：创建一个以 `<branch>` 为目标分支的普通 PR
37+
- `draft`/`for-review`：目前被静默忽略
38+
- `<branch>/<session>`：要打开 PR 的目标分支
39+
- `-o <topic|title|description>`：PR 的选项
40+
- `title`：PR 的标题
41+
- `topic`：PR 应该打开的分支名称
42+
- `description`：PR 的描述
43+
- `force-push`：确认强制更新目标分支
44+
45+
下面是另一个高级示例，用于创建一个以 `topic`、`title` 和 `description` 为参数的新 PR，目标分支是 `master`：
46+
47+
```shell
48+
git push origin HEAD:refs/for/master -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
49+
```

‎docs/content/doc/usage/clone-filter.zh-cn.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
date: "2023-05-23T09:00:00+08:00"
3+
title: "克隆过滤器 (部分克隆)"
4+
slug: "clone-filters"
5+
weight: 25
6+
draft: false
7+
toc: false
8+
aliases:
9+
- /zh-cn/clone-filters
10+
menu:
11+
sidebar:
12+
parent: "usage"
13+
name: "克隆过滤器"
14+
weight: 25
15+
identifier: "clone-filters"
16+
---
17+
18+
# 克隆过滤器 (部分克隆)
19+
20+
Git 引入了 `--filter` 选项用于 `git clone` 命令，该选项可以过滤掉大文件和对象（如 blob），从而创建一个仓库的部分克隆。克隆过滤器对于大型仓库和/或按流量计费的连接特别有用，因为完全克隆（不使用 `--filter`）可能会很昂贵（需要下载所有历史数据）。
21+
22+
这需要 Git 2.22 或更高版本，无论是在 Gitea 服务器上还是在客户端上都需要如此。为了使克隆过滤器正常工作，请确保客户端上的 Git 版本至少与服务器上的版本相同（或更高）。以管理员身份登录到 Gitea，然后转到管理后台 -> 应用配置，查看服务器的 Git 版本。
23+
24+
默认情况下，克隆过滤器是启用的，除非在 `[git]` 下将 `DISABLE_PARTIAL_CLONE` 设置为 `true`。
25+
26+
请参阅 [GitHub 博客文章：了解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以获取克隆过滤器的常见用法（无 Blob 和无树的克隆），以及 [GitLab 部分克隆文档](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。

‎docs/content/doc/usage/incoming-email.zh-cn.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
date: "2023-05-23T09:00:00+08:00"
3+
title: "邮件接收"
4+
slug: "incoming-email"
5+
weight: 13
6+
draft: false
7+
toc: false
8+
aliases:
9+
- /zh-cn/incoming-email
10+
menu:
11+
sidebar:
12+
parent: "usage"
13+
name: "邮件接收"
14+
weight: 13
15+
identifier: "incoming-email"
16+
---
17+
18+
# 邮件接收
19+
20+
Gitea 支持通过接收邮件执行多种操作。本页面描述了如何进行设置。
21+
22+
**目录**
23+
24+
{{< toc >}}
25+
26+
## 要求
27+
28+
处理接收的电子邮件需要启用 IMAP 功能的电子邮件帐户。
29+
推荐的策略是使用 [电子邮件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 邮箱。
30+
接收电子邮件地址中包含一个用户/操作特定的令牌，告诉 Gitea 应执行哪个操作。
31+
此令牌应该出现在 `To` 和 `Delivered-To` 头字段中。
32+
33+
Gitea 会尝试检测自动回复并跳过它们，电子邮件服务器也应该配置以减少接收到的干扰（垃圾邮件、通讯订阅等）。
34+
35+
## 配置
36+
37+
要激活处理接收的电子邮件消息功能，您需要在配置文件中配置 `email.incoming` 部分。
38+
39+
`REPLY_TO_ADDRESS` 包含电子邮件客户端将要回复的地址。
40+
该地址需要包含 `%{token}` 占位符，该占位符将被替换为描述用户/操作的令牌。
41+
此占位符在地址中只能出现一次，并且必须位于地址的用户部分（`@` 之前）。
42+
43+
使用电子邮件子地址的示例可能如下：`incoming+%{token}@example.com`
44+
45+
如果使用 catch-all 邮箱，则占位符可以出现在地址的用户部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com`
46+
47+
## 安全性
48+
49+
在选择用于接收传入电子邮件的域时要小心。
50+
建议在子域名上接收传入电子邮件，例如 `incoming.example.com`，以防止与运行在 `example.com` 上的其他服务可能存在的安全问题。

‎docs/content/doc/usage/labels.zh-cn.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
date: "2023-05-23T09:00:00+08:00"
3+
title: "标签"
4+
slug: "labels"
5+
weight: 13
6+
toc: false
7+
draft: false
8+
aliases:
9+
- /zh-cn/labels
10+
menu:
11+
sidebar:
12+
parent: "usage"
13+
name: "标签"
14+
weight: 13
15+
identifier: "labels"
16+
---
17+
18+
# 标签
19+
20+
您可以使用标签对工单和合并请求进行分类，并提高对它们的概览。
21+
22+
## 创建标签
23+
24+
对于仓库，可以在 `工单（Issues）` 中点击 `标签（Labels）` 来创建标签。
25+
26+
对于组织，您可以定义组织级别的标签，这些标签与所有组织仓库共享，包括已存在的仓库和新创建的仓库。可以在组织的 `设置（Settings）` 中创建组织级别的标签。
27+
28+
标签具有必填的名称和颜色，可选的描述，以及必须是独占的或非独占的（见下面的“作用域标签”）。
29+
30+
当您创建一个仓库时，可以通过使用 `工单标签（Issue Labels）` 选项来选择标签集。该选项列出了一些在您的实例上 [全局配置的可用标签集](../customizing-gitea/#labels)。在创建仓库时，这些标签也将被创建。
31+
32+
## 作用域标签
33+
34+
作用域标签用于确保将至多一个具有相同作用域的标签分配给工单或合并请求。例如，如果标签 `kind/bug` 和 `kind/enhancement` 的独占选项被设置，那么工单只能被分类为 bug 或 enhancement 中的一个。
35+
36+
作用域标签的名称必须包含 `/`（不能在名称的任一端）。标签的作用域是基于最后一个 `/` 决定的，因此例如标签 `scope/subscope/item` 的作用域是 `scope/subscope`。
37+
38+
## 按标签筛选
39+
40+
工单和合并请求列表可以按标签进行筛选。选择多个标签将显示具有所有选定标签的工单和合并请求。
41+
42+
通过按住 alt 键并单击标签，可以将具有所选标签的工单和合并请求从列表中排除。

‎docs/content/doc/usage/linked-references.zh-cn.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
date: "2023-05-23T09:00:00+08:00"
3+
title: "自动链接引用"
4+
slug: "automatically-linked-references"
5+
weight: 15
6+
toc: false
7+
draft: false
8+
aliases:
9+
- /zh-cn/automatically-linked-references
10+
menu:
11+
sidebar:
12+
parent: "usage"
13+
name: "自动链接引用s"
14+
weight: 15
15+
identifier: "automatically-linked-references"
16+
---
17+
18+
# 在工单、合并请求和提交消息中的自动链接引用
19+
20+
**目录**
21+
22+
{{< toc >}}
23+
24+
当发布工单、合并请求或评论时，文本描述会被解析以查找引用。这些引用将显示为工单视图中的链接，并且在某些情况下会触发特定的“操作”。
25+
26+
类似地，当列出提交消息时，它们也会被解析，并且当它们被推送到主分支时可以触发“操作”。
27+
28+
为了防止意外创建引用，对于引用的识别有一定的规则。例如，它们不应该包含在代码文本内部。它们还应该在周围的文本中合理清晰（例如，使用空格）。
29+
30+
## 用户、团队和组织提及
31+
32+
当找到形式为 `@username` 的文本，并且 `username` 与现有用户的名称匹配时，将创建一个“提及”引用。这将通过将文本更改为指向该用户个人资料的链接来显示，并根据被提及的用户是否具有访问内容所需的权限来可能创建通知。
33+
34+
示例：
35+
36+
> [@John](#)，你能看一下这个吗？
37+
38+
对于团队和组织也是有效的：
39+
40+
> [@Documenters](#)，我们需要为此进行规划。
41+
> [@CoolCompanyInc](#)，这个问题关系到我们所有人！
42+
43+
团队将在适当时收到邮件通知，但整个组织不会收到通知。
44+
45+
提交消息不会产生用户通知。
46+
47+
## 提交
48+
49+
可以使用提交的 SHA1 哈希或至少七个字符的一部分来引用提交。它们将显示为指向相应提交的链接。
50+
51+
示例：
52+
53+
> 这个错误是在 [e59ff077](#) 中引入的
54+
55+
## 工单和合并请求
56+
57+
可以使用简单的符号 `#1234` 来创建对另一个工单或合并请求的引用，其中 _1234_ 是同一仓库中一个工单或合并请求的编号。这些引用将显示为指向被引用内容的链接。
58+
59+
创建此类型引用的效果是，在被引用的文档中创建一个“通知”，前提是引用的创建者对其具有读取权限。
60+
61+
示例：
62+
63+
> 这似乎与 [#1234](#) 相关
64+
65+
还可以使用形式 `owner/repository#1234` 来引用其他仓库中的工单和合并请求：
66+
67+
> 这似乎与 [mike/compiler#1234](#) 相关
68+
69+
或者也可以使用 `!1234` 符号。虽然在 Gitea 中合并请求是工单的一种形式，但 `#1234` 形式总是链接到工单；如果链接的条目恰好是一个合并请求，Gitea 会适当地进行重定向。而使用 `!1234` 符号，则会创建一个合并请求链接，根据需要会被重定向到工单。然而，如果使用外部跟踪器，这个区别可能很重要，因为工单和合并请求的链接是不能互换的。
70+
71+
## 可操作的引用在合并请求和提交消息中
72+
73+
有时，一个提交或合并请求可能会修复或重新出现在某个特定工单中。Gitea 支持在引用之前加上特定的“关键字”来关闭和重新打开被引用的工单。常见的关键字包括“closes”、“fixes”、“reopens”等。这个列表可以由站点管理员进行 [自定义]({{< ref "doc/administration/config-cheat-sheet.zh-cn.md" >}})。
74+
75+
示例：
76+
77+
> 这个合并请求 _closes_ [#1234](#)
78+
79+
如果可操作的引用被接受，这将在被引用的工单上创建一个通知，宣布当引用的合并请求被合并时该工单将被关闭。
80+
81+
为了接受可操作的引用，必须满足以下至少一项条件之一：
82+
83+
- 评论者在创建引用时具有关闭或重新打开工单的权限。
84+
- 引用位于提交消息中。
85+
- 引用作为合并请求描述的一部分发布。
86+
87+
在最后一种情况下，只有当合并合并请求的人具有相应权限时，工单才会被关闭或重新打开。
88+
89+
此外，只有合并请求和提交消息可以创建一个操作，只有工单可以通过这种方式被关闭或重新打开。
90+
91+
默认的关键字如下：
92+
93+
- **关闭工单**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
94+
- **重新打开工单**: reopen, reopens, reopened
95+
96+
## 合并请求和提交消息中的时间跟踪
97+
98+
当提交或合并合并请求导致自动关闭工单时，还可以通过提交消息添加解决此工单所花费的时间。
99+
100+
要指定解决工单所花费的时间，需要在工单编号后面以 `@<number><time-unit>` 的格式指定时间。在一个提交消息中，可以指定多个已解决的工单，并为每个工单指定花费的时间。
101+
102+
支持的时间单位（`<time-unit>`）：
103+
104+
- `m` - 分钟
105+
- `h` - 小时
106+
- `d` - 天（相当于8小时）
107+
- `w` - 周（相当于5天）
108+
- `mo` - 月（相当于4周）
109+
110+
用于指定时间的数字（`<number>`）也可以是小数，例如 `@1.5h` 表示一小时半。多个时间单位可以结合使用，例如 `@1h10m` 表示1小时10分钟。
111+
112+
提交消息示例：
113+
114+
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
115+
116+
这将导致工单 #123 增加 1 小时，工单 #124 增加 1 小时半。
117+
118+
## 外部跟踪器
119+
120+
Gitea 支持使用外部工单跟踪器，并可以在合并请求中创建对外部托管的工单的引用。但是，如果外部跟踪器使用数字来标识工单，那么它们将与 Gitea 中托管的合并请求无法区分。为了解决这个工单，Gitea 允许使用 `!` 标记来标识合并请求。例如：
121+
122+
> 这是工单 [#1234](#)，并链接到外部跟踪器。
123+
> 这是合并请求 [!1234](#)，并链接到 Gitea 中的合并请求。
124+
125+
在工单和合并请求中，`!` 和 `#` 可以互换使用，除非需要进行区分。如果仓库使用外部跟踪器，默认情况下，合并提交消息将使用 `!` 作为引用。
126+
127+
## 工单和合并请求引用摘要
128+
129+
下表说明了工单和合并请求的不同类型的交叉引用。在示例中，`User1/Repo1` 指的是使用引用的仓库，而 `UserZ/RepoZ` 表示另一个仓库。
130+
131+
| 在 User1/Repo1 中的引用 | Repo1 的工单是外部的 | RepoZ 的工单是外部的 | 渲染效果 |
132+
| ----------------------- | :-------------------: | :-------------------: | ------------------------------------------------ |
133+
| `#1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
134+
| `!1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
135+
| `#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ 1234 |
136+
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
137+
| `User1/Repo1#1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
138+
| `User1/Repo1!1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
139+
| `User1/Repo1#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ 1234 |
140+
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
141+
| `UserZ/RepoZ#1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234 |
142+
| `UserZ/RepoZ!1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234 |
143+
| `UserZ/RepoZ#1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工单_ 1234 |
144+
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _PR_ 1234 |
145+
| **字母数字工单编号:** | - | - | - |
146+
| `AAA-1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ `AAA-1234` |
147+
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
148+
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
149+
| _不支持_ | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工单_ `AAA-1234` |
150+
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 中的 _PR_ 1234 |
151+
152+
_最后一部分适用于使用字母数字格式的外部工单跟踪器的仓库。_
153+
154+
_**-**: 不适用_
155+
156+
注意：不完全支持具有不同类型工单（外部 vs. 内部）的仓库之间的自动引用，可能会导致无效链接。

‎docs/content/doc/usage/merge-message-templates.zh-cn.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
date: "2023-05-23T09:00:00+08:00"
3+
title: "合并消息模板"
4+
slug: "merge-message-templates"
5+
weight: 15
6+
toc: false
7+
draft: false
8+
aliases:
9+
- /zh-cn/merge-message-templates
10+
menu:
11+
sidebar:
12+
parent: "usage"
13+
name: "合并消息模板"
14+
weight: 15
15+
identifier: "merge-message-templates"
16+
---
17+
18+
# 合并消息模板
19+
20+
**目录**
21+
22+
{{< toc >}}
23+
24+
## 文件名
25+
26+
PR 默认合并消息模板可能的文件名：
27+
28+
- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
29+
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
30+
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
31+
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
32+
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
33+
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
34+
35+
## 变量
36+
37+
您可以在这些模板中使用以下以 `${}` 包围的变量，这些变量遵循 [os.Expand](https://pkg.go.dev/os#Expand) 语法：
38+
39+
- BaseRepoOwnerName：此合并请求的基础仓库所有者名称
40+
- BaseRepoName：此合并请求的基础仓库名称
41+
- BaseBranch：此合并请求的基础仓库目标分支名称
42+
- HeadRepoOwnerName：此合并请求的源仓库所有者名称
43+
- HeadRepoName：此合并请求的源仓库名称
44+
- HeadBranch：此合并请求的源仓库分支名称
45+
- PullRequestTitle：合并请求的标题
46+
- PullRequestDescription：合并请求的描述
47+
- PullRequestPosterName：合并请求的提交者名称
48+
- PullRequestIndex：合并请求的索引号
49+
- PullRequestReference：合并请求的引用字符与索引号。例如，#1、!2
50+
- ClosingIssues：返回一个包含将由此合并请求关闭的所有工单的字符串。例如 `close #1, close #2`
51+
52+
## 变基（Rebase）
53+
54+
在没有合并提交的情况下进行变基时，`REBASE_TEMPLATE.md` 修改最后一次提交的消息。此模板还提供以下附加变量：
55+
56+
- CommitTitle：提交的标题
57+
- CommitBody：提交的正文文本

0 commit comments

Comments
 (0)