mirror of
https://gitea.com/gitea/docs.git
synced 2026-06-29 07:34:22 +00:00
cb462089e9
Reviewed-on: https://gitea.com/gitea/docs/pulls/265 Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: ifurther <55025025+ifurther@users.noreply.github.com> Co-committed-by: ifurther <55025025+ifurther@users.noreply.github.com>
144 lines
8.5 KiB
Markdown
144 lines
8.5 KiB
Markdown
---
|
||
date: "2023-05-23T09:00:00+08:00"
|
||
slug: "automatically-linked-references"
|
||
sidebar_position: 15
|
||
aliases:
|
||
- /zh-tw/automatically-linked-references
|
||
---
|
||
|
||
# 自动链接引用
|
||
|
||
当發佈工單、合並請求或评论时，文本描述会被解析以查找引用。这些引用将显示為工單视图中的链接，並且在某些情况下会触发特定的“操作”。
|
||
|
||
类似地，当列出提交消息时，它们也会被解析，並且当它们被推送到主分支时可以触发“操作”。
|
||
|
||
為了防止意外建立引用，對於引用的识别有一定的規則。例如，它们不應該包含在代码文本内部。它们還應該在周围的文本中合理清晰（例如，使用空格）。
|
||
|
||
## 使用者、团队和組織提及
|
||
|
||
当找到形式為 `@username` 的文本，並且 `username` 与現有使用者的名稱匹配时，将建立一个“提及”引用。这将通過将文本更改為指向該使用者个人资料的链接来显示，並根据被提及的使用者是否具有访问内容所需的权限来可能建立通知。
|
||
|
||
示例：
|
||
|
||
> [@John](#)，你能看一下这个吗？
|
||
|
||
對於团队和組織也是有效的：
|
||
|
||
> [@Documenters](#)，我们需要為此進行规划。
|
||
> [@CoolCompanyInc](#)，这个问题关系到我们所有人！
|
||
|
||
团队将在适当时收到邮件通知，但整个組織不会收到通知。
|
||
|
||
提交消息不会产生使用者通知。
|
||
|
||
## 提交
|
||
|
||
可以使用提交的 SHA1 哈希或至少七个字符的一部分来引用提交。它们将显示為指向相應提交的链接。
|
||
|
||
示例：
|
||
|
||
> 这个错误是在 [e59ff077](#) 中引入的
|
||
|
||
## 工單和合並請求
|
||
|
||
可以使用简單的符号 `#1234` 来建立对另一个工單或合並請求的引用，其中 _1234_ 是同一存放庫中一个工單或合並請求的编号。这些引用将显示為指向被引用内容的链接。
|
||
|
||
建立此類型引用的效果是，在被引用的文檔中建立一个“通知”，前提是引用的建立者对其具有读取权限。
|
||
|
||
示例：
|
||
|
||
> 这似乎与 [#1234](#) 相关
|
||
|
||
還可以使用形式 `owner/repository#1234` 来引用其他存放庫中的工單和合並請求：
|
||
|
||
> 这似乎与 [mike/compiler#1234](#) 相关
|
||
|
||
或者也可以使用 `!1234` 符号。虽然在 Gitea 中合並請求是工單的一种形式，但 `#1234` 形式总是链接到工單；如果链接的条目恰好是一个合並請求，Gitea 会适当地進行重定向。而使用 `!1234` 符号，则会建立一个合並請求链接，根据需要会被重定向到工單。然而，如果使用外部跟踪器，这个区别可能很重要，因為工單和合並請求的链接是不能互换的。
|
||
|
||
## 可操作的引用在合並請求和提交消息中
|
||
|
||
有时，一个提交或合並請求可能会修复或重新出現在某个特定工單中。Gitea 支持在引用之前加上特定的“关键字”来关闭和重新打开被引用的工單。常见的关键字包括“closes”、“fixes”、“reopens”等。这个列表可以由站点管理员進行 [自定义](../administration/config-cheat-sheet.md)。
|
||
|
||
示例：
|
||
|
||
> 这个合並請求 _closes_ [#1234](#)
|
||
|
||
如果可操作的引用被接受，这将在被引用的工單上建立一个通知，宣布当引用的合並請求被合並时該工單将被关闭。
|
||
|
||
為了接受可操作的引用，必須满足以下至少一项条件之一：
|
||
|
||
- 评论者在建立引用时具有关闭或重新打开工單的权限。
|
||
- 引用位于提交消息中。
|
||
- 引用作為合並請求描述的一部分發佈。
|
||
|
||
在最后一种情况下，只有当合並合並請求的人具有相應权限时，工單才会被关闭或重新打开。
|
||
|
||
此外，只有合並請求和提交消息可以建立一个操作，只有工單可以通過这种方式被关闭或重新打开。
|
||
|
||
默认的关键字如下：
|
||
|
||
- **关闭工單**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
|
||
- **重新打开工單**: reopen, reopens, reopened
|
||
|
||
## 合並請求和提交消息中的时间跟踪
|
||
|
||
当提交或合並合並請求导致自动关闭工單时，還可以通過提交消息添加解决此工單所花费的时间。
|
||
|
||
要指定解决工單所花费的时间，需要在工單编号后面以 `@<number><time-unit>` 的格式指定时间。在一个提交消息中，可以指定多个已解决的工單，並為每个工單指定花费的时间。
|
||
|
||
支持的时间單位（`<time-unit>`）：
|
||
|
||
- `m` - 分钟
|
||
- `h` - 小时
|
||
- `d` - 天（相当于 8 小时）
|
||
- `w` - 周（相当于 5 天）
|
||
- `mo` - 月（相当于 4 周）
|
||
|
||
用于指定时间的数字（`<number>`）也可以是小数，例如 `@1.5h` 表示一小时半。多个时间單位可以结合使用，例如 `@1h10m` 表示 1 小时 10 分钟。
|
||
|
||
提交消息示例：
|
||
|
||
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
|
||
|
||
这将导致工單 #123 增加 1 小时，工單 #124 增加 1 小时半。
|
||
|
||
## 外部跟踪器
|
||
|
||
Gitea 支持使用外部工單跟踪器，並可以在合並請求中建立对外部托管的工單的引用。但是，如果外部跟踪器使用数字来标识工單，那么它们将与 Gitea 中托管的合並請求無法区分。為了解决这个问题，Gitea 允许使用 `!` 标记来标识合並請求。例如：
|
||
|
||
> 这是工單 [#1234](#)，並链接到外部跟踪器。
|
||
> 这是合並請求 [!1234](#)，並链接到 Gitea 中的合並請求。
|
||
|
||
在工單和合並請求中，`!` 和 `#` 可以互换使用，除非需要進行区分。如果存放庫使用外部跟踪器，默认情况下，合並提交消息将使用 `!` 作為引用。
|
||
|
||
## 工單和合並請求引用摘要
|
||
|
||
下表说明了工單和合並請求的不同類型的交叉引用。在示例中，`User1/Repo1` 指的是使用引用的存放庫，而 `UserZ/RepoZ` 表示另一个存放庫。
|
||
|
||
| 在 User1/Repo1 中的引用 | Repo1 的工單是外部的 | RepoZ 的工單是外部的 | 渲染效果 |
|
||
| ----------------------- | :------------------: | :------------------: | --------------------------------------------- |
|
||
| `#1234` | 否 | - | 链接到 `User1/Repo1` 中的工單/合並請求 1234 |
|
||
| `!1234` | 否 | - | 链接到 `User1/Repo1` 中的工單/合並請求 1234 |
|
||
| `#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工單_ 1234 |
|
||
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||
| `User1/Repo1#1234` | 否 | - | 链接到 `User1/Repo1` 中的工單/合並請求 1234 |
|
||
| `User1/Repo1!1234` | 否 | - | 链接到 `User1/Repo1` 中的工單/合並請求 1234 |
|
||
| `User1/Repo1#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工單_ 1234 |
|
||
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||
| `UserZ/RepoZ#1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工單/合並請求 1234 |
|
||
| `UserZ/RepoZ!1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工單/合並請求 1234 |
|
||
| `UserZ/RepoZ#1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工單_ 1234 |
|
||
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _PR_ 1234 |
|
||
| **字母数字工單编号:** | - | - | - |
|
||
| `AAA-1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工單_ `AAA-1234` |
|
||
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||
| _不支持_ | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工單_ `AAA-1234` |
|
||
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 中的 _PR_ 1234 |
|
||
|
||
_最后一部分适用于使用字母数字格式的外部工單跟踪器的存放庫。_
|
||
|
||
_**-**: 不适用_
|
||
|
||
注意：不完全支持具有不同類型工單（外部 vs. 内部）的存放庫之间的自动引用，可能会导致無效链接。
|