gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-06-11 04:31:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Upgrade docusarus and fix broken links (#301)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/301
This commit is contained in:
Lunny Xiao
2025-11-20 22:02:05 +00:00
parent 0868bd41a4
commit df8b7a7581
24 changed files with 840 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
babel.config.js
View File

@@ -1,3 +0,0 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

6
docs/administration/customizing-gitea.md
View File

@@ -9,7 +9,7 @@ aliases:
# Customizing Gitea
Customizing Gitea is typically done using the `CustomPath` folder - by default this is
the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/installation.md) has
the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/from-binary.md) has
set this differently. This is the central place to override configuration settings,
templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
the path on the _Configuration_ tab in the _Site Administration_ page. You can override
@@ -23,7 +23,7 @@ the Linux Filesystem Standard. Gitea will attempt to create required folders, in
`custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
Application settings can be found in file `CustomConf` which is by default,
`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/installation.md) has set this differently.
`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/from-binary.md) has set this differently.
Again `gitea help` will allow you review this variable and you can override it using the
`--config` option on the `gitea` binary.
@@ -414,7 +414,7 @@ The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/lab
`#hex-color label name ; label description`
For more information, see the [labels documentation](usage/labels.md).
For more information, see the [labels documentation](../usage/issues-prs/labels.md).
### Licenses

76
docs/contributing/contributing.md Normal file
View File

@@ -0,0 +1,76 @@
---
slug: "contributing"
sidebar_position: 1
---
# Contributing to Gitea
Thank you for your interest in contributing to Gitea! This guide will help you understand how to contribute to the project effectively.
## Getting Started
Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea.md) guide to set up your development environment.
## Contribution Guidelines
We have specific guidelines for different types of contributions:
### Backend Development
If you're working on backend code (Go), please follow our [Guidelines for Backend Development](guidelines-backend.md). This includes:
- Package design and dependencies
- Database operations and migrations
- Testing strategies
- Code organization
### Frontend Development
For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](guidelines-frontend.md). This covers:
- Framework usage (Vue3, Fomantic-UI)
- Code style and best practices
- Accessibility requirements
- TypeScript usage
### Refactoring
When refactoring existing code, follow our [Guidelines for Refactoring](guidelines-refactoring.md) to ensure:
- Clear refactoring objectives
- Proper review process
- Maintaining backward compatibility
- Incremental improvements
### Localization
To contribute translations or localization improvements, see our [Localization Guide](localization.md) which explains:
- How to contribute translations via Crowdin
- Supported languages
- Translation workflow
## Code of Conduct
Please be respectful and constructive in all interactions with the community. We are committed to providing a welcoming and inclusive environment for all contributors.
## Getting Help
If you need help with your contribution:
- Join our [Discord](https://discord.gg/gitea) #Develop channel
- Visit our [Forum](https://forum.gitea.com/)
- Check existing [GitHub Issues](https://github.com/go-gitea/gitea/issues)
## Submitting Your Contribution
1. Fork the repository
2. Create a feature branch
3. Make your changes following the relevant guidelines
4. Write tests for your changes
5. Ensure all tests pass
6. Submit a pull request
For more details, see our [CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) in the main repository.
Thank you for helping make Gitea better!

2
docs/development/hacking-on-gitea.md
View File

@@ -174,7 +174,7 @@ server as mentioned above.
### Working on JS and CSS
Frontend development should follow [Guidelines for Frontend Development](contributing/guidelines-frontend.md)
Frontend development should follow [Guidelines for Frontend Development](../contributing/guidelines-frontend.md)
To build with frontend resources, either use the `watch-frontend` target mentioned above or just build once:

2
docs/usage/actions/quickstart.md
View File

@@ -76,7 +76,7 @@ And you can see the new runner in the management page:
![view runner](/images/usage/actions/view-runner.png)
You can find more information by visiting [Act runner](usage/actions/act-runner.md).
You can find more information by visiting [Act runner](act-runner.mdxc).
### Use Actions

2
docs/usage/issues-prs/labels.md
View File

@@ -18,7 +18,7 @@ For organizations, you can define organization-wide labels that are shared with
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
## Scoped Labels

2
docs/usage/issues-prs/linked-references.md
View File

@@ -85,7 +85,7 @@ Sometimes a commit or pull request may fix or bring back a problem documented
in a particular issue. Gitea supports closing and reopening the referenced
issues by preceding the reference with a particular _keyword_. Common keywords
include "closes", "fixes", "reopens", etc. This list can be
[customized](../administration/config-cheat-sheet.md) by the
[customized](../../administration/config-cheat-sheet.md) by the
site administrator.
Example:

2
docs/usage/issues-prs/pull-request.md
View File

@@ -57,4 +57,4 @@ The first value of the list will be used in helpers.
## Pull Request Templates
You can find more information about pull request templates at the page [Issue and Pull Request templates](usage/issue-pull-request-templates.md).
You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates.md).

4
docusaurus.config.js
View File

@@ -193,7 +193,6 @@ const config = {
url: "https://docs.gitea.com",
baseUrl: "/",
onBrokenLinks: "warn",
onBrokenMarkdownLinks: "warn",
favicon: "img/favicon.png",
future: {
experimental_faster: true,
@@ -329,6 +328,9 @@ const config = {
apiConfig,
],
markdown: {
hooks: {
onBrokenMarkdownLinks: "warn",
},
preprocessor: ({ filePath, fileContent }) => {
var key = "";
var found = false;

8
package-lock.json generated
View File

@@ -8,9 +8,9 @@
"name": "gitea-docs",
"version": "0.0.0",
"dependencies": {
"@docusaurus/core": "^3.4.0",
"@docusaurus/faster": "^3.7.0",
"@docusaurus/preset-classic": "^3.4.0",
"@docusaurus/core": "^3.9.2",
"@docusaurus/faster": "^3.9.2",
"@docusaurus/preset-classic": "^3.9.2",
"@easyops-cn/docusaurus-search-local": "^0.52.0",
"@emotion/react": "^11.11.3",
"@emotion/styled": "^11.11.0",
@@ -23,7 +23,7 @@
"redocusaurus": "^2.0.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.4.0",
"@docusaurus/module-type-aliases": "^3.9.2",
"cross-env": "^10.0.0"
},
"engines": {

8
package.json
View File

@@ -16,9 +16,9 @@
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "^3.4.0",
"@docusaurus/faster": "^3.7.0",
"@docusaurus/preset-classic": "^3.4.0",
"@docusaurus/core": "^3.9.2",
"@docusaurus/faster": "^3.9.2",
"@docusaurus/preset-classic": "^3.9.2",
"@easyops-cn/docusaurus-search-local": "^0.52.0",
"@emotion/react": "^11.11.3",
"@emotion/styled": "^11.11.0",
@@ -31,7 +31,7 @@
"redocusaurus": "^2.0.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.4.0",
"@docusaurus/module-type-aliases": "^3.9.2",
"cross-env": "^10.0.0"
},
"browserslist": {

3
sidebars.js
View File

@@ -61,7 +61,8 @@ module.exports = {
type: 'category',
label: 'Contributing',
link: {
"type": "generated-index"
"type": "doc",
"id": "contributing/contributing"
},
items: [
{

2
versioned_docs/version-1.23/administration/customizing-gitea.md
View File

@@ -321,7 +321,7 @@ The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/lab
`#hex-color label name ; label description`
For more information, see the [labels documentation](usage/labels.md).
For more information, see the [labels documentation](../usage/labels.md).
### Licenses

48
versioned_docs/version-1.23/usage/agit.md Normal file
View File

@@ -0,0 +1,48 @@
---
date: " 2022-09-01T20:50:42+0000"
slug: "agit"
sidebar_position: 12
aliases:
- /en-us/agit-setup
- /agit-setup
---
# AGit
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
:::note
Git version 2.29 or higher is required on the server side for this to work.
:::
## Creating PRs with AGit
AGit allows to create PRs while pushing code to the remote repo.
This can be done by pushing to the branch followed by a specific refspec (a location identifier known to git).
The following example illustrates this:
```shell
git push origin HEAD:refs/for/main
```
The command has the following structure:
- `HEAD`: The target branch
- `origin`: The target repository (not a fork!)
- `HEAD`: The local branch containing the changes you are proposing
- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
- `for`: Create a normal PR with `<branch>` as the target branch
- `draft`/`for-review`: Currently ignored silently
- `<branch>/`: The branch you want your changes to be merged into
- `-o <topic|title|description>`: Options for the PR
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review. This is REQUIRED to trigger a pull request.
- `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
- `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
- `force-push=true`: Specifies whether to force-update the target branch.
- Note: omitting the value and using just `-o force-push` will also work.
Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
```shell
git push origin HEAD:refs/for/main -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"
```

328
versioned_docs/version-1.23/usage/issue-pull-request-templates.md Normal file
View File

@@ -0,0 +1,328 @@
---
date: "2018-05-10T16:00:00+02:00"
slug: "issue-pull-request-templates"
sidebar_position: 15
aliases:
- /en-us/issue-pull-request-templates
---
# Issue and Pull Request Templates
Some projects have a standard list of questions that users need to answer
when creating an issue or pull request. Gitea supports adding templates to the
**default branch of the repository** so that they can autopopulate the form when users are
creating issues and pull requests. This will cut down on the initial back and forth
of getting some clarifying details.
It is currently not possible to provide generic issue/pull-request templates globally.
Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
## File names
Possible file names for issue templates:
- `ISSUE_TEMPLATE.md`
- `ISSUE_TEMPLATE.yaml`
- `ISSUE_TEMPLATE.yml`
- `issue_template.md`
- `issue_template.yaml`
- `issue_template.yml`
- `.gitea/ISSUE_TEMPLATE.md`
- `.gitea/ISSUE_TEMPLATE.yaml`
- `.gitea/ISSUE_TEMPLATE.yml`
- `.gitea/issue_template.md`
- `.gitea/issue_template.yaml`
- `.gitea/issue_template.yml`
- `.github/ISSUE_TEMPLATE.md`
- `.github/ISSUE_TEMPLATE.yaml`
- `.github/ISSUE_TEMPLATE.yml`
- `.github/issue_template.md`
- `.github/issue_template.yaml`
- `.github/issue_template.yml`
Possible file names for issue config:
- `.gitea/ISSUE_TEMPLATE/config.yaml`
- `.gitea/ISSUE_TEMPLATE/config.yml`
- `.gitea/issue_template/config.yaml`
- `.gitea/issue_template/config.yml`
- `.github/ISSUE_TEMPLATE/config.yaml`
- `.github/ISSUE_TEMPLATE/config.yml`
- `.github/issue_template/config.yaml`
- `.github/issue_template/config.yml`
Possible file names for PR templates:
- `PULL_REQUEST_TEMPLATE.md`
- `PULL_REQUEST_TEMPLATE.yaml`
- `PULL_REQUEST_TEMPLATE.yml`
- `pull_request_template.md`
- `pull_request_template.yaml`
- `pull_request_template.yml`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
- `.gitea/PULL_REQUEST_TEMPLATE.yml`
- `.gitea/pull_request_template.md`
- `.gitea/pull_request_template.yaml`
- `.gitea/pull_request_template.yml`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/PULL_REQUEST_TEMPLATE.yaml`
- `.github/PULL_REQUEST_TEMPLATE.yml`
- `.github/pull_request_template.md`
- `.github/pull_request_template.yaml`
- `.github/pull_request_template.yml`
## Directory names
Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically
addresses their problem.
Possible directory names for issue templates:
- `ISSUE_TEMPLATE`
- `issue_template`
- `.gitea/ISSUE_TEMPLATE`
- `.gitea/issue_template`
- `.github/ISSUE_TEMPLATE`
- `.github/issue_template`
- `.gitlab/ISSUE_TEMPLATE`
- `.gitlab/issue_template`
Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) issue templates of the form.
## Syntax for markdown template
```md
---
name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
assignees: ["user1"]
labels:
- bug
- "help needed"
---
This is the template!
```
In the above example, when a user is presented with the list of issues they can submit, this would show as `Template Name` with the description
`This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with
`[TEST] ` while the issue body would be pre-populated with `This is the template!`.
The issue would be assigned to `user1`.
The issue would also be assigned two labels,
`bug` and `help needed`, and the issue will have a reference to `main`.
## Syntax for yaml template
This example YAML configuration file defines an issue form using several inputs to report a bug.
```yaml
name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
# some markdown that will only be visible once the issue has been created
- type: markdown
attributes:
value: |
This issue was created by an issue **template** :)
visible: [content]
- type: input
id: contact
attributes:
label: Contact Details
description: How can we get in touch with you if we need more info?
placeholder: ex. email@example.com
validations:
required: false
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
validations:
required: true
- type: dropdown
id: version
attributes:
label: Version
description: What version of our software are you running?
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: dropdown
id: browsers
attributes:
label: What browsers are you seeing the problem on?
multiple: true
options:
- Firefox
- Chrome
- Safari
- Microsoft Edge
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: shell
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
hide_label: true
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
options:
- label: I agree to follow this project's Code of Conduct
required: true
- label: I have also read the CONTRIBUTION.MD
required: true
visible: [form]
- label: This is a TODO only visible after issue creation
visible: [content]
```
### Markdown
You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted by default.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------|--------------------------------------------------------------|----------|--------|---------|--------------|
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
visible: Default is **[form]**
### Textarea
You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|--------------|---------------------------|
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the text area. | Optional | String | - | - |
| render | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | - | Languages known to Gitea. |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
visible: Default is **[form, content]**
### Input
You can use an `input` element to add a single-line text field to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|--------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - |
| value | Text that is pre-filled in the field. | Optional | String | - | - |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
| is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - |
| regex | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String | - | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
visible: Default is **[form, content]**
### Dropdown
You can use a `dropdown` element to add a dropdown menu in your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
| multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - |
| list | If true, display as a list. If false, print items on one line with commas. | Optional | Boolean | false | - |
| options | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | Required | String array | - | - |
Validations:
| Key | Description | Required | Type | Default | Valid values |
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
visible: Default is **[form, content]**
### Checkboxes
You can use the `checkboxes` element to add a set of checkboxes to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
|-------------|-------------------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
| hide_label | If true, the label normally used as a headline is not visible. | Optional | Boolean | false | - |
| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - |
| options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - |
For each value in the options array, you can set the following keys.
| Key | Description | Required | Type | Default | Options |
|--------------|------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------|---------|---------|
| label | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String | - | - |
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
| visible | Whether a specific checkbox appears in the form only, in the created issue only, or both. Valid options are "form" and "content". | Optional | String array | false | - |
visible: Default is **[form, content]**
## Syntax for issue config
This is a example for a issue config file
```yaml
blank_issues_enabled: true
contact_links:
- name: Gitea
url: https://gitea.com
about: Visit the Gitea Website
```
### Possible Options
| Key | Description | Type | Default |
|----------------------|-------------------------------------------------------|--------------------|-------------|
| blank_issues_enabled | If set to false, the User is forced to use a Template | Boolean | true |
| contact_links | Custom Links to show in the Choose Box | Contact Link Array | Empty Array |
### Contact Link
| Key | Description | Type | Required |
|-------|----------------------------------|--------|----------|
| name | the name of your link | String | true |
| url | The URL of your Link | String | true |
| about | A short description of your Link | String | true |

33
versioned_docs/version-1.23/usage/labels.md Normal file
View File

@@ -0,0 +1,33 @@
---
date: "2023-03-04T19:00:00+00:00"
slug: "labels"
sidebar_position: 13
aliases:
- /en-us/labels
---
# Labels
You can use labels to classify issues and pull requests and to improve your overview over them.
## Creating Labels
For repositories, labels can be created by going to `Issues` and clicking on `Labels`.
For organizations, you can define organization-wide labels that are shared with all organization repositories, including both already-existing repositories as well as newly created ones. Organization-wide labels can be created in the organization `Settings`.
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
## Scoped Labels
Scoped labels are used to ensure at most a single label with the same scope is assigned to an issue or pull request. For example, if labels `kind/bug` and `kind/enhancement` have the Exclusive option set, an issue can only be classified as a bug or an enhancement.
A scoped label must contain `/` in its name (not at either end of the name). The scope of a label is determined based on the **last** `/`, so for example the scope of label `scope/subscope/item` is `scope/subscope`.
## Filtering by Label
Issue and pull request lists can be filtered by label. Selecting multiple labels shows issues and pull requests that have all selected labels assigned.
By holding alt to click the label, issues and pull requests with the chosen label are excluded from the list.

194
versioned_docs/version-1.23/usage/linked-references.md Normal file
View File

@@ -0,0 +1,194 @@
---
date: "2019-11-21T17:00:00-03:00"
slug: "automatically-linked-references"
sidebar_position: 15
aliases:
- /en-us/automatically-linked-references
---
# Automatically Linked References
When an issue, pull request or comment is posted, the text description is parsed
in search for references. These references will be shown as links in the Issue View
and, in some cases, produce certain _actions_.
Likewise, commit messages are parsed when they are listed, and _actions_
can be triggered when they are pushed to the main branch.
To prevent the creation of unintended references, there are certain rules
for them to be recognized. For example, they should not be included inside code
text. They should also be reasonably cleared from their surrounding text
(for example, using spaces).
## User, Team and Organization Mentions
When a text in the form `@username` is found and `username` matches the name
of an existing user, a _mention_ reference is created. This will be shown
by changing the text into a link to said user's profile, and possibly create
a notification for the mentioned user depending on whether they have
the necessary permission to access the contents.
Example:
> [@John](#), can you give this a look?
This is also valid for teams and organizations:
> [@Documenters](#), we need to plan for this.
> [@CoolCompanyInc](#), this issue concerns us all!
Teams will receive mail notifications when appropriate, but whole organizations won't.
Commit messages do not produce user notifications.
## Commits
Commits can be referenced using their SHA1 hash, or a portion of it of
at least seven characters. They will be shown as a link to the corresponding
commit.
Example:
> This bug was introduced in [e59ff077](#)
## Issues and Pull Requests
A reference to another issue or pull request can be created using the simple
notation `#1234`, where _1234_ is the number of an issue or pull request
in the same repository. These references will be shown as links to the
referenced content.
The effect of creating this type of reference is that a _notice_ will be
created in the referenced document, provided the creator of the reference
has reading permissions on it.
Example:
> This seems related to [#1234](#)
Issues and pull requests in other repositories can be referred to as well
using the form `owner/repository#1234`:
> This seems related to [mike/compiler#1234](#)
Alternatively, the `!1234` notation can be used as well. Even when in Gitea
a pull request is a form of issue, the `#1234` form will always link to
an issue; if the linked entry happens to be a pull request instead, Gitea
will redirect as appropriate. With the `!1234` notation, a pull request
link will be created, which will be redirected to an issue if required.
However, this distinction could be important if an external tracker is
used, where links to issues and pull requests are not interchangeable.
## Actionable References in Pull Requests and Commit Messages
Sometimes a commit or pull request may fix or bring back a problem documented
in a particular issue. Gitea supports closing and reopening the referenced
issues by preceding the reference with a particular _keyword_. Common keywords
include "closes", "fixes", "reopens", etc. This list can be
[customized](../administration/config-cheat-sheet.md) by the
site administrator.
Example:
> This PR _closes_ [#1234](#)
If the actionable reference is accepted, this will create a notice on the
referenced issue announcing that it will be closed when the referencing PR
is merged.
For an actionable reference to be accepted, _at least one_ of the following
conditions must be met:
- The commenter has permissions to close or reopen the issue at the moment
of creating the reference.
- The reference is inside a commit message.
- The reference is posted as part of the pull request description.
In the last case, the issue will be closed or reopened only if the merger
of the pull request has permissions to do so.
Additionally, only pull requests and commit messages can create an action,
and only issues can be closed or reopened this way.
The default _keywords_ are:
- **Closing**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
- **Reopening**: reopen, reopens, reopened
## Time tracking in Pull Requests and Commit Messages
When commit or merging of pull request results in automatic closing of issue
it is possible to also add spent time resolving this issue through commit message.
To specify spent time on resolving issue you need to specify time in format
`@<number><time-unit>` after issue number. In one commit message you can specify
multiple fixed issues and spent time for each of them.
Supported time units (`<time-unit>`):
- `m` - minutes
- `h` - hours
- `d` - days (equals to 8 hours)
- `w` - weeks (equals to 5 days)
- `mo` - months (equals to 4 weeks)
Numbers to specify time (`<number>`) can be also decimal numbers, ex. `@1.5h` would
result in one and half hours. Multiple time units can be combined, ex. `@1h10m` would
mean 1 hour and 10 minutes.
Example of commit message:
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
This would result in 1 hour added to issue #123 and 1 and half hours added to issue #124.
## External Trackers
Gitea supports the use of external issue trackers, and references to issues
hosted externally can be created in pull requests. However, if the external
tracker uses numbers to identify issues, they will be indistinguishable from
the pull requests hosted in Gitea. To address this, Gitea allows the use of
the `!` marker to identify pull requests. For example:
> This is issue [#1234](#), and links to the external tracker.
> This is pull request [!1234](#), and links to a pull request in Gitea.
The `!` and `#` can be used interchangeably for issues and pull request _except_
for this case, where a distinction is required. If the repository uses external
tracker, commit message for squash merge will use `!` as reference by default.
## Issues and Pull Requests References Summary
This table illustrates the different kinds of cross-reference for issues and pull requests.
In the examples, `User1/Repo1` refers to the repository where the reference is used, while
`UserZ/RepoZ` indicates a different repository.
| Reference in User1/Repo1 | Repo1 issues are external | RepoZ issues are external | Should render |
| --------------------------- | :-----------------------: | :-----------------------: | ------------------------------------------------------- |
| `#1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` |
| `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |
| `User1/Repo1#1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `User1/Repo1!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` |
| `User1/Repo1#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` |
| `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |
| `UserZ/RepoZ#1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
| `UserZ/RepoZ#1234` | - | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 for `UserZ/RepoZ` |
| **Alphanumeric issue IDs:** | - | - | - |
| `AAA-1234` | yes | - | A link to _external issue_ `AAA-1234` for `User1/Repo1` |
| `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |
| `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` |
| _Not supported_ | - | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` |
| `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 in `UserZ/RepoZ` |
_The last section is for repositories with external issue trackers that use alphanumeric format._
_**-**: not applicable._
:::note
Automatic references between repositories with different types of issues (external vs. internal) are not fully supported
and may render invalid links.
:::

46
versioned_docs/version-1.23/usage/merge-message-templates.md Normal file
View File

@@ -0,0 +1,46 @@
---
date: "2022-08-31T17:35:40+08:00"
slug: "merge-message-templates"
sidebar_position: 15
aliases:
- /en-us/merge-message-templates
---
# Merge Message templates
## File names
Possible file names for PR default merge message templates:
- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
## Variables
You can use the following variables enclosed in `${}` inside these templates which follow [os.Expand](https://pkg.go.dev/os#Expand) syntax:
- BaseRepoOwnerName: Base repository owner name of this pull request
- BaseRepoName: Base repository name of this pull request
- BaseBranch: Base repository target branch name of this pull request
- HeadRepoOwnerName: Head repository owner name of this pull request
- HeadRepoName: Head repository name of this pull request
- HeadBranch: Head repository branch name of this pull request
- PullRequestTitle: Pull request's title
- PullRequestDescription: Pull request's description
- PullRequestPosterName: Pull request's poster name
- PullRequestIndex: Pull request's index number
- PullRequestReference: Pull request's reference char with index number. i.e. #1, !2
- ClosingIssues: return a string contains all issues which will be closed by this pull request i.e. `close #1, close #2`
- ReviewedOn: Which pull request this commit belongs to. For example `Reviewed-on: https://gitea.com/foo/bar/pulls/1`
- ReviewedBy: Who approved the pull request before the merge. For example `Reviewed-by: Jane Doe <jane.doe@example.com>`
## Rebase
When rebasing without a merge commit, `REBASE_TEMPLATE.md` modifies the message of the last commit. The following additional variables are available in this template:
- CommitTitle: Commit's title
- CommitBody: Commits's body text

86
versioned_docs/version-1.23/usage/template-repositories.md Normal file
View File

@@ -0,0 +1,86 @@
---
date: "2019-11-28:00:00+02:00"
slug: "template-repositories"
sidebar_position: 14
aliases:
- /en-us/template-repositories
---
# Template Repositories
Since Gitea `1.11`, you can create template repositories.
When creating a repo based on a template, you can copy most of its content, and even auto-inject variables into it.
By default, variables will not be expanded in any file.
Only files contained in a pattern inside the `.gitea/template` file will be checked for if they contain variables.
When creating the template, all files are included except for this `.gitea/template` file.
Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax.
It closely resembles a traditional `.gitignore`, however there may be slight differences.
## Example `.gitea/template` file
All paths are relative to the base of the repository
```gitignore
# Expand all .go files, anywhere in the repository
**.go
# All text files in the text directory
text/*.txt
# A specific file
a/b/c/d.json
# Batch files in both upper or lower case can be matched
**.[bB][aA][tT]
```
## Variable Expansion
In any file matched by the above globs, the variables below will be expanded.
Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems.
You can use variables by prefixing them with `$` or surrounding them with `${}`, so both `$VAR` and `${VAR}` insert the value of `VAR` at this location.
To escape an expansion, use `$$`, such as `$$VAR` or `$${VAR}`.
These are the variables Gitea currently recognizes:
| Variable | Expands To | Transformable |
| -------------------- | --------------------------------------------------- | ------------- |
| YEAR | The year of generating the repository (i.e. `2024`) | ✘ |
| MONTH | The month of generating the repository (i.e. `03`) | ✘ |
| MONTH_ENGLISH | The month but in English (i.e. `March`) | ✓ |
| DAY | The day of generating the repository (i.e. `02`) | ✘ |
| REPO_NAME | The name of the generated repository | ✓ |
| TEMPLATE_NAME | The name of the template repository | ✓ |
| REPO_DESCRIPTION | The description of the generated repository | ✘ |
| TEMPLATE_DESCRIPTION | The description of the template repository | ✘ |
| REPO_OWNER | The owner of the generated repository | ✓ |
| TEMPLATE_OWNER | The owner of the template repository | ✓ |
| REPO_LINK | The URL to the generated repository | ✘ |
| TEMPLATE_LINK | The URL to the template repository | ✘ |
| REPO_HTTPS_URL | The HTTP(S) clone link for the generated repository | ✘ |
| TEMPLATE_HTTPS_URL | The HTTP(S) clone link for the template repository | ✘ |
| REPO_SSH_URL | The SSH clone link for the generated repository | ✘ |
| TEMPLATE_SSH_URL | The SSH clone link for the template repository | ✘ |
## Transformers :robot:
Since Gitea `1.12.0`, variables marked as transformable in the table above also have alternative versions where the given transformer has been applied.
Transformed variables can be called by appending the transformer name to the variable name.
For example, to get `REPO_NAME` in `PASCAL`-case, you should use the variable `${REPO_NAME_PASCAL}`.
The following transformers are available (assuming `go-sdk` is the input):
| Transformer | Effect |
| ----------- | ------ |
| SNAKE | go_sdk |
| KEBAB | go-sdk |
| CAMEL | goSdk |
| PASCAL | GoSdk |
| LOWER | go-sdk |
| UPPER | GO-SDK |
| TITLE | Go-Sdk |

6
versioned_docs/version-1.25/administration/customizing-gitea.md
View File

@@ -9,7 +9,7 @@ aliases:
# Customizing Gitea
Customizing Gitea is typically done using the `CustomPath` folder - by default this is
the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/installation.md) has
the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/from-binary.md) has
set this differently. This is the central place to override configuration settings,
templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
the path on the _Configuration_ tab in the _Site Administration_ page. You can override
@@ -23,7 +23,7 @@ the Linux Filesystem Standard. Gitea will attempt to create required folders, in
`custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
Application settings can be found in file `CustomConf` which is by default,
`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/installation.md) has set this differently.
`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/from-binary.md) has set this differently.
Again `gitea help` will allow you review this variable and you can override it using the
`--config` option on the `gitea` binary.
@@ -414,7 +414,7 @@ The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/lab
`#hex-color label name ; label description`
For more information, see the [labels documentation](usage/labels.md).
For more information, see the [labels documentation](../usage/issues-prs/labels.md).
### Licenses

2
versioned_docs/version-1.25/usage/issues-prs/labels.md
View File

@@ -18,7 +18,7 @@ For organizations, you can define organization-wide labels that are shared with
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
## Scoped Labels

2
versioned_docs/version-1.25/usage/issues-prs/linked-references.md
View File

@@ -85,7 +85,7 @@ Sometimes a commit or pull request may fix or bring back a problem documented
in a particular issue. Gitea supports closing and reopening the referenced
issues by preceding the reference with a particular _keyword_. Common keywords
include "closes", "fixes", "reopens", etc. This list can be
[customized](../administration/config-cheat-sheet.md) by the
[customized](../../administration/config-cheat-sheet.md) by the
site administrator.
Example:

2
versioned_docs/version-1.25/usage/issues-prs/pull-request.md
View File

@@ -57,4 +57,4 @@ The first value of the list will be used in helpers.
## Pull Request Templates
You can find more information about pull request templates at the page [Issue and Pull Request templates](usage/issue-pull-request-templates.md).
You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates.md).

2
versioned_docs/version-1.25/usage/repository/push.md
View File

@@ -44,7 +44,7 @@ Push to create is a feature that allows you to push to a repository that does no
### Enabling Push To Create
In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../administration/config-cheat-sheet.md#repository-repository).
In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#repository-repository).
### Using Push To Create