tdsds.com/gitea
1
1
Fork 0
mirror of https://github.com/go-gitea/gitea synced 2025-07-22 18:28:37 +00:00
Code Releases Activity

Reformat docs (#13897)

Browse Source 
Co-authored-by: 6543 <6543@obermui.de>
Co-authored-by: Lauris BH <lauris@nix.lv>
This commit is contained in:
Patrick Schratz
2020-12-09 07:47:06 +01:00
committed by GitHub
parent 97ab820acc
commit af79677a44
86 changed files with 1115 additions and 957 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/content/doc/advanced/cmd-embedded.en-us.md
View File

@@ -3,7 +3,7 @@ date: "2020-01-25T21:00:00-03:00"
title: "Embedded data extraction tool"
slug: "cmd-embedded"
weight: 40
toc: true
toc: false
draft: false
menu:
sidebar:
@@ -15,6 +15,10 @@ menu:
# Embedded data extraction tool
**Table of Contents**
{{< toc >}}
Gitea's executable contains all the resources required to run: templates, images, style-sheets
and translations. Any of them can be overridden by placing a replacement in a matching path
inside the `custom` directory (see [Customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}})).
@@ -28,7 +32,7 @@ can be used from the OS shell interface.
To list resources embedded in Gitea's executable, use the following syntax:
```
```sh
gitea embedded list [--include-vendored] [patterns...]
```
@@ -48,11 +52,11 @@ a special meaning for your command shell.
If no pattern is provided, all files are listed.
#### Example
### Example
Listing all embedded files with `openid` in their path:
```
```sh
$ gitea embedded list '**openid**'
public/img/auth/openid_connect.svg
public/img/openid-16x16.png
@@ -68,7 +72,7 @@ templates/user/settings/security_openid.tmpl
To extract resources embedded in Gitea's executable, use the following syntax:
```
```sh
gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...}
```
@@ -91,7 +95,7 @@ as `filename.bak`. Previous `.bak` files are overwritten.
At least one file search pattern must be provided; see `list` subcomand above for pattern
syntax and examples.
#### Important notice
### Important notice
Make sure to **only extract those files that require customization**. Files that
are present in the `custom` directory are not upgraded by Gitea's upgrade process.
@@ -99,11 +103,11 @@ When Gitea is upgraded to a new version (by replacing the executable), many of t
embedded files will suffer changes. Gitea will honor and use any files found
in the `custom` directory, even if they are old and incompatible.
#### Example
### Example
Extracting mail templates to a temporary directory:
```
```sh
$ mkdir tempdir
$ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
Extracting to tempdir:

66
docs/content/doc/advanced/customizing-gitea.en-us.md
View File

@@ -45,7 +45,7 @@ environment variable; this can be used to override the default path to something
**Note:** Gitea must perform a full restart to see configuration changes.
# Table of Contents
**Table of Contents**
{{< toc >}}
@@ -127,8 +127,8 @@ copy javascript files from https://gitea.com/davidsvantesson/plantuml-code-highl
<script src="https://your-server.com/encode.js"></script>
<script src="https://your-server.com/plantuml_codeblock_parse.js"></script>
<script>
<!-- Replace call with address to your plantuml server-->
parsePlantumlCodeBlocks("http://www.plantuml..com/plantuml")
<!-- Replace call with address to your plantuml server-->
parsePlantumlCodeBlocks("http://www.plantuml..com/plantuml");
</script>
{{end}}
```
@@ -148,38 +148,50 @@ The script will detect tags with `class="language-plantuml"`, but you can change
#### Example: STL Preview
You can display STL file directly in Gitea by adding:
```html
<script>
function lS(src){
return new Promise(function(resolve, reject) {
let s = document.createElement('script')
s.src = src
s.addEventListener('load', () => {
resolve()
})
document.body.appendChild(s)
});
}
if($('.view-raw>a[href$=".stl" i]').length){
$('body').append('<link href="/Madeleine.js/src/css/Madeleine.css" rel="stylesheet">');
Promise.all([lS("/Madeleine.js/src/lib/stats.js"),lS("/Madeleine.js/src/lib/detector.js"), lS("/Madeleine.js/src/lib/three.min.js"), lS("/Madeleine.js/src/Madeleine.js")]).then(function() {
$('.view-raw').attr('id', 'view-raw').attr('style', 'padding: 0;margin-bottom: -10px;');
new Madeleine({
target: 'view-raw',
data: $('.view-raw>a[href$=".stl" i]').attr('href'),
path: '/Madeleine.js/src'
function lS(src) {
return new Promise(function (resolve, reject) {
let s = document.createElement("script");
s.src = src;
s.addEventListener("load", () => {
resolve();
});
document.body.appendChild(s);
});
$('.view-raw>a[href$=".stl"]').remove()
});
}
}
if ($('.view-raw>a[href$=".stl" i]').length) {
$("body").append(
'<link href="/Madeleine.js/src/css/Madeleine.css" rel="stylesheet">'
);
Promise.all([
lS("/Madeleine.js/src/lib/stats.js"),
lS("/Madeleine.js/src/lib/detector.js"),
lS("/Madeleine.js/src/lib/three.min.js"),
lS("/Madeleine.js/src/Madeleine.js"),
]).then(function () {
$(".view-raw")
.attr("id", "view-raw")
.attr("style", "padding: 0;margin-bottom: -10px;");
new Madeleine({
target: "view-raw",
data: $('.view-raw>a[href$=".stl" i]').attr("href"),
path: "/Madeleine.js/src",
});
$('.view-raw>a[href$=".stl"]').remove();
});
}
</script>
```
to the file `templates/custom/footer.tmpl`
You also need to download the content of the library [Madeleine.js](https://jinjunho.github.io/Madeleine.js/) and place it under `custom/public/` folder.
You should end-up with a folder structucture similar to:
```
custom/templates
-- custom
@@ -267,7 +279,7 @@ To add a custom license, add a file with the license text to `custom/options/lic
Locales are managed via our [crowdin](https://crowdin.com/project/gitea).
You can override a locale by placing an altered locale file in `custom/options/locale`.
Gitea's default locale files can be found in the [`options/locale`](https://github.com/go-gitea/gitea/tree/master/options/locale) source folder and these should be used as examples for your changes.
Gitea's default locale files can be found in the [`options/locale`](https://github.com/go-gitea/gitea/tree/master/options/locale) source folder and these should be used as examples for your changes.
To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them.
@@ -289,10 +301,12 @@ currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.S
### Reactions
To change reaction emoji's you can set allowed reactions at app.ini
```
[ui]
REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes
```
A full list of supported emoji's is at [emoji list](https://gitea.com/gitea/gitea.com/issues/8)
## Customizing the look of Gitea

48
docs/content/doc/advanced/environment-variables.en-us.md
View File

@@ -15,11 +15,15 @@ menu:
# Environment variables
**Table of Contents**
{{< toc >}}
This is an inventory of Gitea environment variables. They change Gitea behaviour.
Initialize them before Gitea command to be effective, for example:
```
```sh
GITEA_CUSTOM=/home/gitea/custom ./gitea web
```
@@ -27,42 +31,42 @@ GITEA_CUSTOM=/home/gitea/custom ./gitea web
As Gitea is written in Go, it uses some Go variables, such as:
* `GOOS`
* `GOARCH`
* [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
- `GOOS`
- `GOARCH`
- [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
For documentation about each of the variables available, refer to the
[official Go documentation](https://golang.org/cmd/go/#hdr-Environment_variables).
## Gitea files
* `GITEA_WORK_DIR`: Absolute path of working directory.
* `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
to change *custom* directory.
* `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
* `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
- `GITEA_WORK_DIR`: Absolute path of working directory.
- `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
to change _custom_ directory.
- `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
- `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
## Operating system specifics
* `USER`: System user that Gitea will run as. Used for some repository access strings.
* `USERNAME`: if no `USER` found, Gitea will use `USERNAME`
* `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows.
- `USER`: System user that Gitea will run as. Used for some repository access strings.
- `USERNAME`: if no `USER` found, Gitea will use `USERNAME`
- `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows.
### Only on Windows
* `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH`
* `HOMEDRIVE`: Main drive path used to access the home directory (C:)
* `HOMEPATH`: Home relative path in the given home drive path
- `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH`
- `HOMEDRIVE`: Main drive path used to access the home directory (C:)
- `HOMEPATH`: Home relative path in the given home drive path
## Macaron (framework used by Gitea)
* `HOST`: Host Macaron will listen on
* `PORT`: Port Macaron will listen on
* `MACARON_ENV`: global variable to provide special functionality for development environments
vs. production environments. If MACARON_ENV is set to "" or "development", then templates will
be recompiled on every request. For more performance, set the MACARON_ENV environment variable
to "production".
- `HOST`: Host Macaron will listen on
- `PORT`: Port Macaron will listen on
- `MACARON_ENV`: global variable to provide special functionality for development environments
vs. production environments. If MACARON_ENV is set to "" or "development", then templates will
be recompiled on every request. For more performance, set the MACARON_ENV environment variable
to "production".
## Miscellaneous
* `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.
- `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.

16
docs/content/doc/advanced/external-renderers.en-us.md
View File

@@ -3,7 +3,7 @@ date: "2018-11-23:00:00+02:00"
title: "External renderers"
slug: "external-renderers"
weight: 40
toc: true
toc: false
draft: false
menu:
sidebar:
@@ -15,12 +15,16 @@ menu:
# Custom files rendering configuration
**Table of Contents**
{{< toc >}}
Gitea supports custom file renderings (i.e., Jupyter notebooks, asciidoc, etc.) through external binaries,
it is just a matter of:
* installing external binaries
* add some configuration to your `app.ini` file
* restart your Gitea instance
- installing external binaries
- add some configuration to your `app.ini` file
- restart your Gitea instance
This supports rendering of whole files. If you want to render code blocks in markdown you would need to do something with javascript. See some examples on the [Customizing Gitea](../customizing-gitea) page.
@@ -29,7 +33,7 @@ This supports rendering of whole files. If you want to render code blocks in mar
In order to get file rendering through external binaries, their associated packages must be installed.
If you're using a Docker image, your `Dockerfile` should contain something along this lines:
```
```docker
FROM gitea/gitea:{{< version >}}
[...]
@@ -49,7 +53,7 @@ RUN pip3 install jupyter docutils
add one `[markup.XXXXX]` section per external renderer on your custom `app.ini`:
```
```ini
[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc

184
docs/content/doc/advanced/logging-documentation.en-us.md
View File

@@ -3,7 +3,7 @@ date: "2019-04-02T17:06:00+01:00"
title: "Advanced: Logging Configuration"
slug: "logging-configuration"
weight: 55
toc: true
toc: false
draft: false
menu:
sidebar:
@@ -17,6 +17,8 @@ menu:
The logging framework has been revamped in Gitea 1.9.0.
**Table of Contents**
{{< toc >}}
## Log Groups
@@ -24,11 +26,11 @@ The logging framework has been revamped in Gitea 1.9.0.
The fundamental thing to be aware of in Gitea is that there are several
log groups:
* The "Default" logger
* The Macaron logger
* The Router logger
* The Access logger
* The XORM logger
- The "Default" logger
- The Macaron logger
- The Router logger
- The Access logger
- The XORM logger
There is also the go log logger.
@@ -55,11 +57,11 @@ which inherits from the sublogger `[log.sublogger]` section and from the
generic `[log]` section, but there are certain default values. These will
not be inherited from the `[log]` section:
* `FLAGS` is `stdflags` (Equal to
`date,time,medfile,shortfuncname,levelinitial`)
* `FILE_NAME` will default to `%(ROOT_PATH)/gitea.log`
* `EXPRESSION` will default to `""`
* `PREFIX` will default to `""`
- `FLAGS` is `stdflags` (Equal to
`date,time,medfile,shortfuncname,levelinitial`)
- `FILE_NAME` will default to `%(ROOT_PATH)/gitea.log`
- `EXPRESSION` will default to `""`
- `PREFIX` will default to `""`
The provider type of the sublogger can be set using the `MODE` value in
its subsection, but will default to the name. This allows you to have
@@ -82,11 +84,11 @@ Each output sublogger for this logger is configured in
which will not be inherited from the `[log]` or relevant
`[log.sublogger]` sections:
* `FLAGS` is `stdflags` (Equal to
`date,time,medfile,shortfuncname,levelinitial`)
* `FILE_NAME` will default to `%(ROOT_PATH)/macaron.log`
* `EXPRESSION` will default to `""`
* `PREFIX` will default to `""`
- `FLAGS` is `stdflags` (Equal to
`date,time,medfile,shortfuncname,levelinitial`)
- `FILE_NAME` will default to `%(ROOT_PATH)/macaron.log`
- `EXPRESSION` will default to `""`
- `PREFIX` will default to `""`
NB: You can redirect the macaron logger to send its events to the gitea
log using the value: `MACARON = ,`
@@ -113,10 +115,10 @@ Each output sublogger for this logger is configured in
which will not be inherited from the `[log]` or relevant
`[log.sublogger]` sections:
* `FILE_NAME` will default to `%(ROOT_PATH)/router.log`
* `FLAGS` defaults to `date,time`
* `EXPRESSION` will default to `""`
* `PREFIX` will default to `""`
- `FILE_NAME` will default to `%(ROOT_PATH)/router.log`
- `FLAGS` defaults to `date,time`
- `EXPRESSION` will default to `""`
- `PREFIX` will default to `""`
NB: You can redirect the router logger to send its events to the Gitea
log using the value: `ROUTER = ,`
@@ -138,10 +140,10 @@ Each output sublogger for this logger is configured in
which will not be inherited from the `[log]` or relevant
`[log.sublogger]` sections:
* `FILE_NAME` will default to `%(ROOT_PATH)/access.log`
* `FLAGS` defaults to `` or None
* `EXPRESSION` will default to `""`
* `PREFIX` will default to `""`
- `FILE_NAME` will default to `%(ROOT_PATH)/access.log`
- `FLAGS` defaults to `` or None
- `EXPRESSION` will default to `""`
- `PREFIX` will default to `""`
If desired the format of the Access logger can be changed by changing
the value of the `ACCESS_LOG_TEMPLATE`.
@@ -160,11 +162,11 @@ This value represent a go template. It's default value is:
The template is passed following options:
* `Ctx` is the `macaron.Context`
* `Identity` is the `SignedUserName` or `"-"` if the user is not logged
in
* `Start` is the start time of the request
* `ResponseWriter` is the `macaron.ResponseWriter`
- `Ctx` is the `macaron.Context`
- `Identity` is the `SignedUserName` or `"-"` if the user is not logged
in
- `Start` is the start time of the request
- `ResponseWriter` is the `macaron.ResponseWriter`
Caution must be taken when changing this template as it runs outside of
the standard panic recovery trap. The template should also be as simple
@@ -187,31 +189,31 @@ Each output sublogger for this logger is configured in
which will not be inherited from the `[log]` or relevant
`[log.sublogger]` sections:
* `FILE_NAME` will default to `%(ROOT_PATH)/xorm.log`
* `FLAGS` defaults to `date,time`
* `EXPRESSION` will default to `""`
* `PREFIX` will default to `""`
- `FILE_NAME` will default to `%(ROOT_PATH)/xorm.log`
- `FLAGS` defaults to `date,time`
- `EXPRESSION` will default to `""`
- `PREFIX` will default to `""`
## Log outputs
Gitea provides 4 possible log outputs:
* `console` - Log to `os.Stdout` or `os.Stderr`
* `file` - Log to a file
* `conn` - Log to a keep-alive TCP connection
* `smtp` - Log via email
- `console` - Log to `os.Stdout` or `os.Stderr`
- `file` - Log to a file
- `conn` - Log to a keep-alive TCP connection
- `smtp` - Log via email
Certain configuration is common to all modes of log output:
* `LEVEL` is the lowest level that this output will log. This value
is inherited from `[log]` and in the case of the non-default loggers
from `[log.sublogger]`.
* `STACKTRACE_LEVEL` is the lowest level that this output will print
a stacktrace. This value is inherited.
* `MODE` is the mode of the log output. It will default to the sublogger
name. Thus `[log.console.macaron]` will default to `MODE = console`.
* `COLORIZE` will default to `true` for `console` as
described, otherwise it will default to `false`.
- `LEVEL` is the lowest level that this output will log. This value
is inherited from `[log]` and in the case of the non-default loggers
from `[log.sublogger]`.
- `STACKTRACE_LEVEL` is the lowest level that this output will print
a stacktrace. This value is inherited.
- `MODE` is the mode of the log output. It will default to the sublogger
name. Thus `[log.console.macaron]` will default to `MODE = console`.
- `COLORIZE` will default to `true` for `console` as
described, otherwise it will default to `false`.
### Non-inherited default values
@@ -233,23 +235,23 @@ printed before each message. It is a comma-separated string set. The order of va
Possible values are:
* `none` or `,` - No flags.
* `date` - the date in the local time zone: `2009/01/23`.
* `time` - the time in the local time zone: `01:23:23`.
* `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes
time.
* `longfile` - full file name and line number: `/a/b/c/d.go:23`.
* `shortfile` - final file name element and line number: `d.go:23`.
* `funcname` - function name of the caller: `runtime.Caller()`.
* `shortfuncname` - last part of the function name. Overrides
`funcname`.
* `utc` - if date or time is set, use UTC rather than the local time
zone.
* `levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info.
* `level` - Provided level in brackets `[INFO]`
* `medfile` - Last 20 characters of the filename - equivalent to
`shortfile,longfile`.
* `stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial`
- `none` or `,` - No flags.
- `date` - the date in the local time zone: `2009/01/23`.
- `time` - the time in the local time zone: `01:23:23`.
- `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes
time.
- `longfile` - full file name and line number: `/a/b/c/d.go:23`.
- `shortfile` - final file name element and line number: `d.go:23`.
- `funcname` - function name of the caller: `runtime.Caller()`.
- `shortfuncname` - last part of the function name. Overrides
`funcname`.
- `utc` - if date or time is set, use UTC rather than the local time
zone.
- `levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info.
- `level` - Provided level in brackets `[INFO]`
- `medfile` - Last 20 characters of the filename - equivalent to
`shortfile,longfile`.
- `stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial`
### Console mode
@@ -267,30 +269,30 @@ to the provided `ROOT_PATH` in the master `[log]` section.
Other values:
* `LOG_ROTATE`: **true**: Rotate the log files.
* `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file, 28 represents 256Mb.
* `DAILY_ROTATE`: **true**: Rotate logs daily.
* `MAX_DAYS`: **7**: Delete the log file after n days
* `COMPRESS`: **true**: Compress old log files by default with gzip
* `COMPRESSION_LEVEL`: **-1**: Compression level
- `LOG_ROTATE`: **true**: Rotate the log files.
- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file, 28 represents 256Mb.
- `DAILY_ROTATE`: **true**: Rotate logs daily.
- `MAX_DAYS`: **7**: Delete the log file after n days
- `COMPRESS`: **true**: Compress old log files by default with gzip
- `COMPRESSION_LEVEL`: **-1**: Compression level
### Conn mode
* `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
* `RECONNECT`: **false**: Try to reconnect when connection is lost.
* `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp".
* `ADDR`: **:7020**: Sets the address to connect to.
- `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
- `RECONNECT`: **false**: Try to reconnect when connection is lost.
- `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp".
- `ADDR`: **:7020**: Sets the address to connect to.
### SMTP mode
It is not recommended to use this logger to send general logging
messages. However, you could perhaps set this logger to work on `FATAL`.
* `USER`: User email address to send from.
* `PASSWD`: Password for the smtp server.
* `HOST`: **127.0.0.1:25**: The SMTP host to connect to.
* `RECEIVERS`: Email addresses to send to.
* `SUBJECT`: **Diagnostic message from Gitea**
- `USER`: User email address to send from.
- `PASSWD`: Password for the smtp server.
- `HOST`: **127.0.0.1:25**: The SMTP host to connect to.
- `RECEIVERS`: Email addresses to send to.
- `SUBJECT`: **Diagnostic message from Gitea**
## Debugging problems
@@ -386,7 +388,7 @@ Windows. Terminal sniffing will occur on Windows and if it is
determined that we are running on a terminal capable of color we will
colorize.
Further, on *nix it is becoming common to have file logs that are
Further, on \*nix it is becoming common to have file logs that are
colored by default. Therefore file logs will be colorised by default
when not running on Windows.
@@ -404,14 +406,14 @@ string of bytes which should represent a color and second set of reset
bytes. Pointers were chosen to prevent copying of large numbers of
values. There are several helper methods:
* `log.NewColoredValue` takes a value and 0 or more color attributes
that represent the color. If 0 are provided it will default to a cached
bold. Note, it is recommended that color bytes constructed from
attributes should be cached if this is a commonly used log message.
* `log.NewColoredValuePointer` takes a pointer to a value, and
0 or more color attributes that represent the color.
* `log.NewColoredValueBytes` takes a value and a pointer to an array
of bytes representing the color.
- `log.NewColoredValue` takes a value and 0 or more color attributes
that represent the color. If 0 are provided it will default to a cached
bold. Note, it is recommended that color bytes constructed from
attributes should be cached if this is a commonly used log message.
- `log.NewColoredValuePointer` takes a pointer to a value, and
0 or more color attributes that represent the color.
- `log.NewColoredValueBytes` takes a value and a pointer to an array
of bytes representing the color.
These functions will not double wrap a `log.ColoredValue`. They will
also set the `resetBytes` to the cached `resetBytes`.
@@ -467,9 +469,9 @@ You should then add `newOneLogService` to `NewServices()` in
Gitea includes built-in log rotation, which should be enough for most deployments. However, if you instead want to use the `logrotate` utility:
- Disable built-in log rotation by setting `LOG_ROTATE` to `false` in your `app.ini`.
- Install `logrotate`.
- Configure `logrotate` to match your deployment requirements, see `man 8 logrotate` for configuration syntax details. In the `postrotate/endscript` block send Gitea a `USR1` signal via `kill -USR1` or `kill -10`, or run `gitea manager logging release-and-reopen` (with the appropriate environment). Ensure that your configurations apply to all files emitted by Gitea loggers as described in the above sections.
- Always do `logrotate /etc/logrotate.conf --debug` to test your configurations.
- Disable built-in log rotation by setting `LOG_ROTATE` to `false` in your `app.ini`.
- Install `logrotate`.
- Configure `logrotate` to match your deployment requirements, see `man 8 logrotate` for configuration syntax details. In the `postrotate/endscript` block send Gitea a `USR1` signal via `kill -USR1` or `kill -10`, or run `gitea manager logging release-and-reopen` (with the appropriate environment). Ensure that your configurations apply to all files emitted by Gitea loggers as described in the above sections.
- Always do `logrotate /etc/logrotate.conf --debug` to test your configurations.
The next `logrotate` jobs will include your configurations, so no restart is needed. You can also immediately reload `logrotate` with `logrotate /etc/logrotate.conf --force`.

116
docs/content/doc/advanced/mail-templates-us.md
View File

@@ -3,7 +3,7 @@ date: "2019-10-23T17:00:00-03:00"
title: "Mail templates"
slug: "mail-templates"
weight: 45
toc: true
toc: false
draft: false
menu:
sidebar:
@@ -15,41 +15,44 @@ menu:
# Mail templates
**Table of Contents**
{{< toc >}}
To craft the e-mail subject and contents for certain operations, Gitea can be customized by using templates. The templates
for these functions are located under the [`custom` directory](https://docs.gitea.io/en-us/customizing-gitea/).
Gitea has an internal template that serves as default in case there's no custom alternative.
Custom templates are loaded when Gitea starts. Changes made to them are not recognized until Gitea is restarted again.
{{< toc >}}
## Mail notifications supporting templates
Currently, the following notification events make use of templates:
| Action name | Usage |
|---------------|--------------------------------------------------------------------------------------------------------------|
| `new` | A new issue or pull request was created. |
| `comment` | A new comment was created in an existing issue or pull request. |
| `close` | An issue or pull request was closed. |
| `reopen` | An issue or pull request was reopened. |
| `review` | The head comment of a review in a pull request. |
| `approve` | The head comment of a approving review for a pull request. |
| `reject` | The head comment of a review requesting changes for a pull request. |
| `code` | A single comment on the code of a pull request. |
| `assigned` | Used was assigned to an issue or pull request. |
| `default` | Any action not included in the above categories, or when the corresponding category template is not present. |
| Action name | Usage |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `new` | A new issue or pull request was created. |
| `comment` | A new comment was created in an existing issue or pull request. |
| `close` | An issue or pull request was closed. |
| `reopen` | An issue or pull request was reopened. |
| `review` | The head comment of a review in a pull request. |
| `approve` | The head comment of a approving review for a pull request. |
| `reject` | The head comment of a review requesting changes for a pull request. |
| `code` | A single comment on the code of a pull request. |
| `assigned` | Used was assigned to an issue or pull request. |
| `default` | Any action not included in the above categories, or when the corresponding category template is not present. |
The path for the template of a particular message type is:
```
```sh
custom/templates/mail/{action type}/{action name}.tmpl
```
Where `{action type}` is one of `issue` or `pull` (for pull requests), and `{action name}` is one of the names listed above.
For example, the specific template for a mail regarding a comment in a pull request is:
```
```sh
custom/templates/mail/pull/comment.tmpl
```
@@ -57,10 +60,10 @@ However, creating templates for each and every action type/name combination is n
A fallback system is used to choose the appropriate template for an event. The _first existing_
template on this list is used:
* The specific template for the desired **action type** and **action name**.
* The template for action type `issue` and the desired **action name**.
* The template for the desired **action type**, action name `default`.
* The template for action type `issue`, action name `default`.
- The specific template for the desired **action type** and **action name**.
- The template for action type `issue` and the desired **action name**.
- The template for the desired **action type**, action name `default`.
- The template for action type `issue`, action name `default`.
The only mandatory template is action type `issue`, action name `default`, which is already embedded in Gitea
unless it's overridden by the user in the `custom` directory.
@@ -84,27 +87,26 @@ Text and macros for the mail body
Specifying a _subject_ section is optional (and therefore also the dash line separator). When used, the separator between
_subject_ and _mail body_ templates requires at least three dashes; no other characters are allowed in the separator line.
_Subject_ and _mail body_ are parsed by [Golang's template engine](https://golang.org/pkg/text/template/) and
are provided with a _metadata context_ assembled for each notification. The context contains the following elements:
| Name | Type | Available | Usage |
|--------------------|------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `.FallbackSubject` | string | Always | A default subject line. See Below. |
| `.Subject` | string | Only in body | The _subject_, once resolved. |
| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. |
| `.Link` | string | Always | The address of the originating issue, pull request or comment. |
| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is *not* a pull request. |
| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. |
| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). |
| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) |
| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. |
| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. |
| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. |
| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. |
| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. |
| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. |
| `.ReviewComments` | []models.Comment | Always | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`. |
| Name | Type | Available | Usage |
| ------------------ | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.FallbackSubject` | string | Always | A default subject line. See Below. |
| `.Subject` | string | Only in body | The _subject_, once resolved. |
| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. |
| `.Link` | string | Always | The address of the originating issue, pull request or comment. |
| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is _not_ a pull request. |
| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. |
| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). |
| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) |
| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. |
| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. |
| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. |
| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. |
| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. |
| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. |
| `.ReviewComments` | []models.Comment | Always | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`. |
All names are case sensitive.
@@ -115,19 +117,19 @@ Please refer to the linked documentation for details about its syntax.
The _subject_ is built using the following steps:
* A template is selected according to the type of notification and to what templates are present.
* The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
- A template is selected according to the type of notification and to what templates are present.
- The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
or pull request).
* All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
* All leading, trailing and redundant spaces are removed.
* The string is truncated to its first 256 runes (characters).
- All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
- All leading, trailing and redundant spaces are removed.
- The string is truncated to its first 256 runes (characters).
If the end result is an empty string, **or** no subject template was available (i.e. the selected template
did not include a subject part), Gitea's **internal default** will be used.
The internal default (fallback) subject is the equivalent of:
```
```sh
{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#.Issue.Index)
```
@@ -171,7 +173,7 @@ Please check [Gitea's logs](https://docs.gitea.io/en-us/logging-configuration/)
`custom/templates/mail/issue/default.tmpl`:
```
```html
[{{.Repo}}] @{{.Doer.Name}}
{{if eq .ActionName "new"}}
created
@@ -247,10 +249,10 @@ This template produces something along these lines:
>
> #### Message content:
>
> \__________________________________________________________________
> \_********************************\_********************************
>
> Mike, I think we should tone down the blues a little.
> \__________________________________________________________________
> \_********************************\_********************************
>
> [View it on Gitea](#).
@@ -259,18 +261,18 @@ This template produces something along these lines:
The template system contains several functions that can be used to further process and format
the messages. Here's a list of some of them:
| Name | Parameters | Available | Usage |
|----------------------|-------------|-----------|------------------------------------------------------------------------------|
| `AppUrl` | - | Any | Gitea's URL |
| `AppName` | - | Any | Set from `app.ini`, usually "Gitea" |
| `AppDomain` | - | Any | Gitea's host name |
| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed |
| `Str2html` | string | Body only | Sanitizes text by removing any HTML tags from it. |
| `Safe` | string | Body only | Takes the input as HTML; can be used for `.ReviewComments.RenderedContent`. |
| Name | Parameters | Available | Usage |
| ---------------- | ----------- | --------- | --------------------------------------------------------------------------- |
| `AppUrl` | - | Any | Gitea's URL |
| `AppName` | - | Any | Set from `app.ini`, usually "Gitea" |
| `AppDomain` | - | Any | Gitea's host name |
| `EllipsisString` | string, int | Any | Truncates a string to the specified length; adds ellipsis as needed |
| `Str2html` | string | Body only | Sanitizes text by removing any HTML tags from it. |
| `Safe` | string | Body only | Takes the input as HTML; can be used for `.ReviewComments.RenderedContent`. |
These are _functions_, not metadata, so they have to be used:
```
```html
Like this: {{Str2html "Escape<my>text"}}
Or this: {{"Escape<my>text" | Str2html}}
Or this: {{AppUrl}}

2
docs/content/doc/advanced/make.fr-fr.md
View File

@@ -3,7 +3,7 @@ date: "2017-08-23T09:00:00+02:00"
title: "Make"
slug: "make"
weight: 10
toc: true
toc: false
draft: false
menu:
sidebar:

2
docs/content/doc/advanced/make.zh-cn.md
View File

@@ -3,7 +3,7 @@ date: "2017-01-14T11:00:00-02:00"
title: "Make 安装"
slug: "make"
weight: 10
toc: true
toc: false
draft: false
menu:
sidebar:

22
docs/content/doc/advanced/repo-indexer.en-us.md
View File

@@ -3,7 +3,7 @@ date: "2019-09-06T01:35:00-03:00"
title: "Repository indexer"
slug: "repo-indexer"
weight: 45
toc: true
toc: false
draft: false
menu:
sidebar:
@@ -15,11 +15,15 @@ menu:
# Repository indexer
**Table of Contents**
{{< toc >}}
## Setting up the repository indexer
Gitea can search through the files of the repositories by enabling this function in your [`app.ini`](https://docs.gitea.io/en-us/config-cheat-sheet/):
```
```ini
[indexer]
; ...
REPO_INDEXER_ENABLED = true
@@ -49,10 +53,10 @@ Limiting the list of files prevents the indexes from becoming polluted with deri
Pattern matching works as follows:
* To match all files with a `.txt` extension no matter what directory, use `**.txt`.
* To match all files with a `.txt` extension _only at the root level of the repository_, use `*.txt`.
* To match all files inside `resources/bin` and below, use `resources/bin/**`.
* To match all files _immediately inside_ `resources/bin`, use `resources/bin/*`.
* To match all files named `Makefile`, use `**Makefile`.
* Matching a directory has no effect; the pattern `resources/bin` will not include/exclude files inside that directory; `resources/bin/**` will.
* All files and patterns are normalized to lower case, so `**Makefile`, `**makefile` and `**MAKEFILE` are equivalent.
- To match all files with a `.txt` extension no matter what directory, use `**.txt`.
- To match all files with a `.txt` extension _only at the root level of the repository_, use `*.txt`.
- To match all files inside `resources/bin` and below, use `resources/bin/**`.
- To match all files _immediately inside_ `resources/bin`, use `resources/bin/*`.
- To match all files named `Makefile`, use `**Makefile`.
- Matching a directory has no effect; the pattern `resources/bin` will not include/exclude files inside that directory; `resources/bin/**` will.
- All files and patterns are normalized to lower case, so `**Makefile`, `**makefile` and `**MAKEFILE` are equivalent.

2
docs/content/doc/advanced/search-engines-indexation.en-us.md
View File

@@ -3,7 +3,7 @@ date: "2019-12-31T13:55:00+05:00"
title: "Advanced: Search Engines Indexation"
slug: "search-engines-indexation"
weight: 30
toc: true
toc: false
draft: false
menu:
sidebar:

72
docs/content/doc/advanced/signing.en-us.md
View File

@@ -15,6 +15,10 @@ menu:
# GPG Commit Signatures
**Table of Contents**
{{< toc >}}
Gitea will verify GPG commit signatures in the provided tree by
checking if the commits are signed by a key within the gitea database,
or if the commit matches the default key for git.
@@ -36,10 +40,10 @@ this requires git >= 2.0.0.
There are a number of places where Gitea will generate commits itself:
* Repository Initialisation
* Wiki Changes
* CRUD actions using the editor or the API
* Merges from Pull Requests
- Repository Initialisation
- Wiki Changes
- CRUD actions using the editor or the API
- Merges from Pull Requests
Depending on configuration and server trust you may want Gitea to
sign these commits.
@@ -78,12 +82,12 @@ MERGES = pubkey, twofa, basesigned, commitssigned
The first option to discuss is the `SIGNING_KEY`. There are three main
options:
* `none` - this prevents Gitea from signing any commits
* `default` - Gitea will default to the key configured within
`git config`
* `KEYID` - Gitea will sign commits with the gpg key with the ID
`KEYID`. In this case you should provide a `SIGNING_NAME` and
`SIGNING_EMAIL` to be displayed for this key.
- `none` - this prevents Gitea from signing any commits
- `default` - Gitea will default to the key configured within
`git config`
- `KEYID` - Gitea will sign commits with the gpg key with the ID
`KEYID`. In this case you should provide a `SIGNING_NAME` and
`SIGNING_EMAIL` to be displayed for this key.
The `default` option will interrogate `git config` for
`commit.gpgsign` option - if this is set, then it will use the results
@@ -99,10 +103,10 @@ ideal UI and therefore subject to change.
This option determines whether Gitea should sign the initial commit
when creating a repository. The possible values are:
* `never`: Never sign
* `pubkey`: Only sign if the user has a public key
* `twofa`: Only sign if the user logs in with two factor authentication
* `always`: Always sign
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two factor authentication
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list.
@@ -112,11 +116,11 @@ separated list.
This options determines if Gitea should sign commits to the Wiki.
The possible values are:
* `never`: Never sign
* `pubkey`: Only sign if the user has a public key
* `twofa`: Only sign if the user logs in with two factor authentication
* `parentsigned`: Only sign if the parent commit is signed.
* `always`: Always sign
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two factor authentication
- `parentsigned`: Only sign if the parent commit is signed.
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list.
@@ -126,11 +130,11 @@ separated list.
This option determines if Gitea should sign commits from the web
editor or API CRUD actions. The possible values are:
* `never`: Never sign
* `pubkey`: Only sign if the user has a public key
* `twofa`: Only sign if the user logs in with two factor authentication
* `parentsigned`: Only sign if the parent commit is signed.
* `always`: Always sign
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two factor authentication
- `parentsigned`: Only sign if the parent commit is signed.
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list.
@@ -140,14 +144,14 @@ separated list.
This option determines if Gitea should sign merge commits from PRs.
The possible options are:
* `never`: Never sign
* `pubkey`: Only sign if the user has a public key
* `twofa`: Only sign if the user logs in with two factor authentication
* `basesigned`: Only sign if the parent commit in the base repo is signed.
* `headsigned`: Only sign if the head commit in the head branch is signed.
* `commitssigned`: Only sign if all the commits in the head branch to the merge point are signed.
* `approved`: Only sign approved merges to a protected branch.
* `always`: Always sign
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two factor authentication
- `basesigned`: Only sign if the parent commit in the base repo is signed.
- `headsigned`: Only sign if the head commit in the head branch is signed.
- `commitssigned`: Only sign if all the commits in the head branch to the merge point are signed.
- `approved`: Only sign approved merges to a protected branch.
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list.
@@ -156,12 +160,12 @@ separated list.
The public key used to sign Gitea's commits can be obtained from the API at:
```
```sh
/api/v1/signing-key.gpg
```
In cases where there is a repository specific key this can be obtained from:
```
```sh
/api/v1/repos/:username/:reponame/signing-key.gpg
```

2
docs/content/doc/advanced/third-party-tools.zh-cn.md
View File

@@ -3,7 +3,7 @@ date: "2019-03-11T21:45:00+00:00"
title: "高级: 第三方工具"
slug: "third-party-tools"
weight: 50
toc: true
toc: false
draft: false
menu:
sidebar: