自動鏈接引用
當發佈問題、拉取請求或評論時,文本描述會被解析以查找引用。這些引用將顯示為問題視圖中的鏈接,並在某些情況下產生某些操作。
同樣,當提交消息被列出時,它們會被解析,並且當它們被推送到主分支時可以觸發操作。
為了防止創建意外引用,有一些規則來識別它們。例如,它們不應包含在代碼文本中。它們還應該與周圍文本合理地分開(例如,使用空格)。
用戶、團隊和組織提及
當找到 @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" 等。此列表可以由站點管理員自定義。
示例:
此 PR closes #1234
如果接受可操作引用,這將在引用的問題上創建一個通知,宣布當合併引用的 PR 時將關閉該問題。
要接受可操作引用,必須滿足以下條件之一:
- 評論者在創建引用時具有關閉或重新打開問題的權限。
- 引用在提交消息中。
- 引用作為拉取請求描述的一部分發佈。
在最後一種情況下,只有在合併拉取請求的人具有權限時,問題才會被關閉或重新打開。
此外,只有拉取請求和提交消息可以創建操作,只有問題可以通過這種方式關閉或重新打開。
默認關鍵字是:
- 關閉: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.5 小時。
外部跟蹤器
Gitea 支援使用外部問題跟蹤器,並且可以在拉取請求中創建對外部託管問題的引用。然而,如果外部跟蹤器使用編號來識別問題,它們將與 Gitea 中託管的拉取請求無法區分。為了解決這個問題,Gitea 允許使用 !
標記來識別拉取請求。例如:
!
和 #
可以互換使用於問題和拉取請求,除了這種情況,需要區分。如果倉庫使用外部跟蹤器,squash 合併的提交消息將默認使用 !
作為引用。
問題和拉取請求引用摘要
此表說明了不同種類的問題和拉取請求的交叉引用。
在示例中,User1/Repo1
指的是使用引用的倉庫,而 UserZ/RepoZ
表示不同的倉庫。
User1/Repo1 中的引用 | Repo1 問題是外部的 | RepoZ 問題是外部的 | 應渲染 |
---|---|---|---|
#1234 | no | - | 指向 User1/Repo1 中問題/拉取請求 1234 的鏈接 |
!1234 | no | - | 指向 User1/Repo1 中問題/拉取請求 1234 的鏈接 |
#1234 | yes | - | 指向 User1/Repo1 的外部問題 1234 的鏈接 |
!1234 | yes | - | 指向 User1/Repo1 的拉取請求 1234 的鏈接 |
User1/Repo1#1234 | no | - | 指向 User1/Repo1 中問題/拉取請求 1234 的鏈接 |
User1/Repo1!1234 | no | - | 指向 User1/Repo1 中問題/拉取請求 1234 的鏈接 |
User1/Repo1#1234 | yes | - | 指向 User1/Repo1 的外部問題 1234 的鏈接 |
User1/Repo1!1234 | yes | - | 指向 User1/Repo1 的拉取請求 1234 的鏈接 |
UserZ/RepoZ#1234 | - | no | 指向 UserZ/RepoZ 中問題/拉取請求 1234 的鏈接 |
UserZ/RepoZ!1234 | - | no | 指向 UserZ/RepoZ 中問題/拉取請求 1234 的鏈接 |
UserZ/RepoZ#1234 | - | yes | 指向 UserZ/RepoZ 的外部問題 1234 的鏈接 |
UserZ/RepoZ!1234 | - | yes | 指向 UserZ/RepoZ 的拉取請求 1234 的鏈接 |
字母數字問題 ID: | - | - | - |
AAA-1234 | yes | - | 指向 User1/Repo1 的外部問題 AAA-1234 的鏈接 |
!1234 | yes | - | 指向 User1/Repo1 的拉取請求 1234 的鏈接 |
User1/Repo1!1234 | yes | - | 指向 User1/Repo1 的拉取請求 1234 的鏈接 |
不支援 | - | yes | 指向 UserZ/RepoZ 的外部問題 AAA-1234 的鏈接 |
UserZ/RepoZ!1234 | - | yes | 指向 UserZ/RepoZ 中的拉取請求 1234 的鏈接 |
最後一部分是針對使用字母數字格式的外部問題跟蹤器的倉庫。
-:不適用。
在具有不同類型問題(外部與內部)的倉庫之間的自動引用尚未完全支援,可能會渲染無效鏈接。