mirror of
https://gitea.com/gitea/docs.git
synced 2026-07-11 21:42:12 +00:00
965c269495
--------- Co-authored-by: silverwind <me@silverwind.io> Co-authored-by: silverwind <2021+silverwind@noreply.gitea.com> Reviewed-on: https://gitea.com/gitea/docs/pulls/455 Reviewed-by: silverwind <2021+silverwind@noreply.gitea.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)。
|
||
|
||
範例：
|
||
|
||
> 這個合併請求 _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. 內部）的存放庫之間的自動引用，可能會導致無效鏈接。
|