code.gitea.io/gitea@v1.22.3/docs/content/usage/linked-references.en-us.md (about) 1 --- 2 date: "2019-11-21T17:00:00-03:00" 3 title: "Automatically Linked References" 4 slug: "automatically-linked-references" 5 sidebar_position: 15 6 toc: false 7 draft: false 8 aliases: 9 - /en-us/automatically-linked-references 10 menu: 11 sidebar: 12 parent: "usage" 13 name: "Automatically Linked References" 14 sidebar_position: 15 15 identifier: "automatically-linked-references" 16 --- 17 18 # Automatically Linked References in Issues, Pull Requests and Commit Messages 19 20 When an issue, pull request or comment is posted, the text description is parsed 21 in search for references. These references will be shown as links in the Issue View 22 and, in some cases, produce certain _actions_. 23 24 Likewise, commit messages are parsed when they are listed, and _actions_ 25 can be triggered when they are pushed to the main branch. 26 27 To prevent the creation of unintended references, there are certain rules 28 for them to be recognized. For example, they should not be included inside code 29 text. They should also be reasonably cleared from their surrounding text 30 (for example, using spaces). 31 32 ## User, Team and Organization Mentions 33 34 When a text in the form `@username` is found and `username` matches the name 35 of an existing user, a _mention_ reference is created. This will be shown 36 by changing the text into a link to said user's profile, and possibly create 37 a notification for the mentioned user depending on whether they have 38 the necessary permission to access the contents. 39 40 Example: 41 42 > [@John](#), can you give this a look? 43 44 This is also valid for teams and organizations: 45 46 > [@Documenters](#), we need to plan for this. 47 > [@CoolCompanyInc](#), this issue concerns us all! 48 49 Teams will receive mail notifications when appropriate, but whole organizations won't. 50 51 Commit messages do not produce user notifications. 52 53 ## Commits 54 55 Commits can be referenced using their SHA1 hash, or a portion of it of 56 at least seven characters. They will be shown as a link to the corresponding 57 commit. 58 59 Example: 60 61 > This bug was introduced in [e59ff077](#) 62 63 ## Issues and Pull Requests 64 65 A reference to another issue or pull request can be created using the simple 66 notation `#1234`, where _1234_ is the number of an issue or pull request 67 in the same repository. These references will be shown as links to the 68 referenced content. 69 70 The effect of creating this type of reference is that a _notice_ will be 71 created in the referenced document, provided the creator of the reference 72 has reading permissions on it. 73 74 Example: 75 76 > This seems related to [#1234](#) 77 78 Issues and pull requests in other repositories can be referred to as well 79 using the form `owner/repository#1234`: 80 81 > This seems related to [mike/compiler#1234](#) 82 83 Alternatively, the `!1234` notation can be used as well. Even when in Gitea 84 a pull request is a form of issue, the `#1234` form will always link to 85 an issue; if the linked entry happens to be a pull request instead, Gitea 86 will redirect as appropriate. With the `!1234` notation, a pull request 87 link will be created, which will be redirected to an issue if required. 88 However, this distinction could be important if an external tracker is 89 used, where links to issues and pull requests are not interchangeable. 90 91 ## Actionable References in Pull Requests and Commit Messages 92 93 Sometimes a commit or pull request may fix or bring back a problem documented 94 in a particular issue. Gitea supports closing and reopening the referenced 95 issues by preceding the reference with a particular _keyword_. Common keywords 96 include "closes", "fixes", "reopens", etc. This list can be 97 [customized](administration/config-cheat-sheet.md) by the 98 site administrator. 99 100 Example: 101 102 > This PR _closes_ [#1234](#) 103 104 If the actionable reference is accepted, this will create a notice on the 105 referenced issue announcing that it will be closed when the referencing PR 106 is merged. 107 108 For an actionable reference to be accepted, _at least one_ of the following 109 conditions must be met: 110 111 - The commenter has permissions to close or reopen the issue at the moment 112 of creating the reference. 113 - The reference is inside a commit message. 114 - The reference is posted as part of the pull request description. 115 116 In the last case, the issue will be closed or reopened only if the merger 117 of the pull request has permissions to do so. 118 119 Additionally, only pull requests and commit messages can create an action, 120 and only issues can be closed or reopened this way. 121 122 The default _keywords_ are: 123 124 - **Closing**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved 125 - **Reopening**: reopen, reopens, reopened 126 127 ## Time tracking in Pull Requests and Commit Messages 128 129 When commit or merging of pull request results in automatic closing of issue 130 it is possible to also add spent time resolving this issue through commit message. 131 132 To specify spent time on resolving issue you need to specify time in format 133 `@<number><time-unit>` after issue number. In one commit message you can specify 134 multiple fixed issues and spent time for each of them. 135 136 Supported time units (`<time-unit>`): 137 138 - `m` - minutes 139 - `h` - hours 140 - `d` - days (equals to 8 hours) 141 - `w` - weeks (equals to 5 days) 142 - `mo` - months (equals to 4 weeks) 143 144 Numbers to specify time (`<number>`) can be also decimal numbers, ex. `@1.5h` would 145 result in one and half hours. Multiple time units can be combined, ex. `@1h10m` would 146 mean 1 hour and 10 minutes. 147 148 Example of commit message: 149 150 > Fixed #123 spent @1h, refs #102, fixes #124 @1.5h 151 152 This would result in 1 hour added to issue #123 and 1 and half hours added to issue #124. 153 154 ## External Trackers 155 156 Gitea supports the use of external issue trackers, and references to issues 157 hosted externally can be created in pull requests. However, if the external 158 tracker uses numbers to identify issues, they will be indistinguishable from 159 the pull requests hosted in Gitea. To address this, Gitea allows the use of 160 the `!` marker to identify pull requests. For example: 161 162 > This is issue [#1234](#), and links to the external tracker. 163 > This is pull request [!1234](#), and links to a pull request in Gitea. 164 165 The `!` and `#` can be used interchangeably for issues and pull request _except_ 166 for this case, where a distinction is required. If the repository uses external 167 tracker, commit message for squash merge will use `!` as reference by default. 168 169 ## Issues and Pull Requests References Summary 170 171 This table illustrates the different kinds of cross-reference for issues and pull requests. 172 In the examples, `User1/Repo1` refers to the repository where the reference is used, while 173 `UserZ/RepoZ` indicates a different repository. 174 175 | Reference in User1/Repo1 | Repo1 issues are external | RepoZ issues are external | Should render | 176 | --------------------------- | :-----------------------: | :-----------------------: | ------------------------------------------------------- | 177 | `#1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` | 178 | `!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` | 179 | `#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` | 180 | `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | 181 | `User1/Repo1#1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` | 182 | `User1/Repo1!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` | 183 | `User1/Repo1#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` | 184 | `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | 185 | `UserZ/RepoZ#1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` | 186 | `UserZ/RepoZ!1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` | 187 | `UserZ/RepoZ#1234` | - | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` | 188 | `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 for `UserZ/RepoZ` | 189 | **Alphanumeric issue IDs:** | - | - | - | 190 | `AAA-1234` | yes | - | A link to _external issue_ `AAA-1234` for `User1/Repo1` | 191 | `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | 192 | `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | 193 | _Not supported_ | - | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` | 194 | `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 in `UserZ/RepoZ` | 195 196 _The last section is for repositories with external issue trackers that use alphanumeric format._ 197 198 _**-**: not applicable._ 199 200 Note: automatic references between repositories with different types of issues (external vs. internal) are not fully supported 201 and may render invalid links.