1
1
mirror of https://github.com/go-gitea/gitea synced 2025-07-03 09:07:19 +00:00

General documentation cleanup (#3317)

* Clean up spelling, grammar, perspective, whitespace, language, markup, etc.
This commit is contained in:
Michael Lustfield
2018-01-08 16:48:42 -06:00
committed by Kim "BKC" Carlbäcker
parent 923c0105f4
commit 3ee8be3849
30 changed files with 500 additions and 279 deletions

View File

@ -15,11 +15,17 @@ menu:
# Configuration Cheat Sheet
This is a cheat sheet for the Gitea configuration file. It contains all settings that can configured.
This is a cheat sheet for the Gitea configuration file. It contains most settings
that can configured as well as their default values.
Any changes to the Gitea configuration file should be made in `custom/conf/app.ini` or any corresponding location. When installing from a distribution, this will typically be found at `/etc/gitea/conf/app.ini`.
Any changes to the Gitea configuration file should be made in `custom/conf/app.ini`
or any corresponding location. When installing from a distribution, this will
typically be found at `/etc/gitea/conf/app.ini`.
The defaults provided here are best-effort (not built automatically). They are accurately recorded in [app.ini.sample](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample) (s/master/<tag|release\>. Any string in the format `%(X)s` is a feature powered by [ini](https://github.com/go-ini/ini/#recursive-values), for reading values recursively.
The defaults provided here are best-effort (not built automatically). They are
accurately recorded in [app.ini.sample](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample)
(s/master/<tag|release\>). Any string in the format `%(X)s` is a feature powered
by [ini](https://github.com/go-ini/ini/#recursive-values), for reading values recursively.
Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
@ -28,22 +34,34 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
## Overall (`DEFAULT`)
- `APP_NAME`: **Gitea: Git with a cup of tea**: Application name, used in the page title.
- `RUN_USER`: **git**: The user Gitea will run as. This should be a dedicated service (non-user) account. Setting this incorrectly will cause Gitea to not start.
- `RUN_MODE`: **dev**: For performance and other purposes, change this to `prod` when deployed to a production environment. The installation process will set this to `prod` automatically. \[prod, dev, test\]
- `RUN_USER`: **git**: The user Gitea will run as. This should be a dedicated system
(non-user) account. Setting this incorrectly will cause Gitea to not start.
- `RUN_MODE`: **dev**: For performance and other purposes, change this to `prod` when
deployed to a production environment. The installation process will set this to `prod`
automatically. \[prod, dev, test\]
## Repository (`repository`)
- `ROOT`: **~/gitea-repositories/**: Root path for storing all repository data. It must be an absolute path.
- `SCRIPT_TYPE`: **bash**: The script type your server supports, usually this is `bash`, but some users report that only `sh` is available.
- `ROOT`: **~/gitea-repositories/**: Root path for storing all repository data. It must be
an absolute path.
- `SCRIPT_TYPE`: **bash**: The script type this server supports, usually this is `bash`,
but some users report that only `sh` is available.
- `ANSI_CHARSET`: **\<empty\>**: The default charset for an unrecognized charset.
- `FORCE_PRIVATE`: **false**: Force every new repository to be private.
- `DEFAULT_PRIVATE`: **last**: Default private when create a new repository. \[last, private, public\]
- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user, `-1` means no limit.
- `PULL_REQUEST_QUEUE_LENGTH`: **1000**: Length of pull request patch test queue, make it as large as possible. Use caution when editing this value.
- `MIRROR_QUEUE_LENGTH`: **1000**: Patch test queue length, increase if pull request patch testing starts hanging.
- `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: Preferred Licenses to place at the top of the List. Name must match file name in conf/license or custom/conf/license.
- `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the HTTP protocol.
- `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when default SSH port is used.
- `DEFAULT_PRIVATE`: **last**: Default private when creating a new repository.
\[last, private, public\]
- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user,
`-1` means no limit.
- `PULL_REQUEST_QUEUE_LENGTH`: **1000**: Length of pull request patch test queue, make it
as large as possible. Use caution when editing this value.
- `MIRROR_QUEUE_LENGTH`: **1000**: Patch test queue length, increase if pull request patch
testing starts hanging.
- `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: Preferred Licenses to place at
the top of the list. Name must match file name in conf/license or custom/conf/license.
- `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the
HTTP protocol.
- `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
default SSH port is used.
## UI (`ui`)
@ -60,40 +78,43 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
## Markdown (`markdown`)
- `ENABLE_HARD_LINE_BREAK`: **false**: Whether or not to enable hard the line break extension.
- `ENABLE_HARD_LINE_BREAK`: **false**: Enable Markdown's hard line break extension.
## Server (`server`)
- `PROTOCOL`: **http**: Either `http`, `https`, `fcgi`, or `unix`.
- `DOMAIN`: **localhost**: Domain name of your server.
- `PROTOCOL`: **http**: \[http, https, fcgi, unix\]
- `DOMAIN`: **localhost**: Domain name of this server.
- `ROOT_URL`: **%(PROTOCOL)s://%(DOMAIN)s:%(HTTP\_PORT)s/**: Full public URL of Gitea server.
- `HTTP_ADDR`: **0.0.0.0**: HTTP listen address.
- If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
- If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket
defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
- If `PROTOCOL` is set to `unix`, this should be the name of the Unix socket file to use.
- `HTTP_PORT`: **3000**: HTTP listen port.
- If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
- `UNIX_SOCKET_PERMISSION`: **666**: Permisson mode for Unix socket.
- `DISABLE_SSH`: **false**: Disables SSH feature when it's not available.
- `START_SSH_SERVER`: **false**: When enabled, uses the built-in SSH server.
- `SSH_DOMAIN`: **%(DOMAIN)s**: Domain name of your ssh server, used for displayed clone URL.
- If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket
defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
- `UNIX_SOCKET_PERMISSION`: **666**: Permissions for the Unix socket.
- `DISABLE_SSH`: **false**: Disable SSH feature when it's not available.
- `START_SSH_SERVER`: **false**: When enabled, use the built-in SSH server.
- `SSH_DOMAIN`: **%(DOMAIN)s**: Domain name of this server, used for displayed clone URL.
- `SSH_PORT`: **22**: SSH port displayed in clone URL.
- `SSH_LISTEN_PORT`: **%(SSH\_PORT)s**: Port for the built-in SSH server.
- `OFFLINE_MODE`: **false**: Disables use of CDN for static files and Gravatar for profile pictures.
- `DISABLE_ROUTER_LOG`: **false**: Mutes printing of the router log.
- `DISABLE_ROUTER_LOG`: **false**: Mute printing of the router log.
- `CERT_FILE`: **custom/https/cert.pem**: Cert file path used for HTTPS.
- `KEY_FILE`: **custom/https/key.pem**: Key file path used for HTTPS.
- `STATIC_ROOT_PATH`: **./**: Upper level of template and static files path.
- `ENABLE_GZIP`: **false**: Enables application-level GZIP support.
- `LANDING_PAGE`: **home**: Landing page for unauthenticated users, either `home` or `explore`.
- `LANDING_PAGE`: **home**: Landing page for unauthenticated users \[home, explore\].
- `LFS_START_SERVER`: **false**: Enables git-lfs support.
- `LFS_CONTENT_PATH`: **./data/lfs**: Where to store lfs files.
- `LFS_CONTENT_PATH`: **./data/lfs**: Where to store LFS files.
- `LFS_JWT_SECRET`: **\<empty\>**: LFS authentication secret, change this a unique string.
- `REDIRECT_OTHER_PORT`: **false**: If true and `PROTOCOL` is https, redirects http requests on another (https) port.
- `REDIRECT_OTHER_PORT`: **false**: If true and `PROTOCOL` is https, redirects http requests
on another (https) port.
- `PORT_TO_REDIRECT`: **80**: Port used when `REDIRECT_OTHER_PORT` is true.
## Database (`database`)
- `DB_TYPE`: **mysql**: The database type you choose, either `mysql`, `postgres`, `mssql` or `sqlite3`.
- `DB_TYPE`: **mysql**: The database type in use \[mysql, postgres, mssql, sqlite3\].
- `HOST`: **127.0.0.1:3306**: Database host address and port.
- `NAME`: **gitea**: Database name.
- `USER`: **root**: Database username.
@ -111,31 +132,41 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
## Security (`security`)
- `INSTALL_LOCK`: **false**: Disable to allow accessing the install page.
- `SECRET_KEY`: **random at every install**: Global secret key. This should be changed.
- `INSTALL_LOCK`: **false**: Disallow access to the install page.
- `SECRET_KEY`: **\<random at every install\>**: Global secret key. This should be changed.
- `LOGIN_REMEMBER_DAYS`: **7**: Cookie lifetime, in days.
- `COOKIE_USERNAME`: **gitea\_awesome**: Name of the cookie used to store the current username.
- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication information.
- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy authentication.
- `DISABLE_GIT_HOOKS`: **false**: Prevent all users (including admin) from creating custom git hooks.
- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
information.
- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
authentication.
- `DISABLE_GIT_HOOKS`: **false**: Prevent all users (including admin) from creating custom
git hooks.
## OpenID (`openid`)
- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
- `WHITELISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching OpenID URI's to permit.
- `BLACKLISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching OpenID URI's to block.
- `WHITELISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching
OpenID URI's to permit.
- `BLACKLISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching
OpenID URI's to block.
## Service (`service`)
- `ACTIVE_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm account/email registration.
- `RESET_PASSWD_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm forgot password reset process.
- `REGISTER_EMAIL_CONFIRM`: **false**: Enable this to ask for mail confirmation of registration. Requires `Mailer` to be enabled.
- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users.
- `RESET_PASSWD_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm forgot password reset
process.
- `REGISTER_EMAIL_CONFIRM`: **false**: Enable this to ask for mail confirmation of registration.
Requires `Mailer` to be enabled.
- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
accounts for users.
- `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page.
- `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when something happens, like creating issues. Requires `Mailer` to be enabled.
- `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when
something happens, like creating issues. Requires `Mailer` to be enabled.
- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication.
- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration for reverse authentication.
- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
for reverse authentication.
- `ENABLE_CAPTCHA`: **true**: Enable this to use captcha validation for registration.
## Webhook (`webhook`)
@ -151,43 +182,52 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
- `DISABLE_HELO`: **\<empty\>**: Disable HELO operation.
- `HELO_HOSTNAME`: **\<empty\>**: Custom hostname for HELO operation.
- `HOST`: **\<empty\>**: SMTP mail host address and port (example: smtp.gitea.io:587).
- `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or the "Name" \<email@example.com\> format.
- `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or
the "Name" \<email@example.com\> format.
- `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address).
- `PASSWD`: **\<empty\>**: Password of mailing user.
- `SKIP_VERIFY`: **\<empty\>**: Do not verify the self-signed certificates.
- **Note:** Gitea only supports SMTP with STARTTLS.
- `USE_SENDMAIL`: **false** Use the operating system's `sendmail` command instead of SMTP. This is common on linux systems.
- Note that enabling sendmail will ignore all other `mailer` settings except `ENABLED`, `FROM` and `SENDMAIL_PATH`.
- `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system. (can be command or full path)
- `USE_SENDMAIL`: **false** Use the operating system's `sendmail` command instead of SMTP.
This is common on linux systems.
- Note that enabling sendmail will ignore all other `mailer` settings except `ENABLED`,
`FROM` and `SENDMAIL_PATH`.
- `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system. (can be
command or full path)
## Cache (`cache`)
- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, or `memcache`. If you want to use `redis` or `memcache`, be sure to rebuild everything with build tags `redis` or `memcache`: `go build -tags='redis'`.
- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, or `memcache`.
- To use `redis` or `memcache`, be sure to rebuild everything with build tags `redis` or
`memcache`: `go build -tags='redis'`.
- `INTERVAL`: **60**: Garbage Collection interval (sec), for memory cache only.
- `HOST`: **\<empty\>**: Connection string for `redis` and `memcache`.
- Redis: `network=tcp,addr=127.0.0.1:6379,password=macaron,db=0,pool_size=100,idle_timeout=180`
- Memache: `127.0.0.1:9090;127.0.0.1:9091`
- Redis: `network=tcp,addr=127.0.0.1:6379,password=macaron,db=0,pool_size=100,idle_timeout=180`
- Memache: `127.0.0.1:9090;127.0.0.1:9091`
## Session (`session`)
- `PROVIDER`: **memory**: Session engine provider, either `memory`, `file`, `redis`, or `mysql`.
- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, mysql\].
- `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for others, the connection string.
- `COOKIE_SECURE`: **false**: Enable this to force using HTTPS for all session access.
- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID, defaults to `i_like_gitea`.
- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID.
- `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
## Picture (`picture`)
- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo` or anything like `http://cn.gravatar.com/avatar/`.
- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo` or anything like
`http://cn.gravatar.com/avatar/`.
- `DISABLE_GRAVATAR`: **false**: Enable this to use local avatars only.
- `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see http://www.libravatar.org)
- `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see
http://www.libravatar.org)
- `AVATAR_UPLOAD_PATH`: **data/avatars**: Path to store local and cached files.
## Attachment (`attachment`)
- `ENABLED`: **true**: Enable this to allow uploading attachments.
- `PATH`: **data/attachments**: Path to store attachments.
- `ALLOWED_TYPES`: **see app.ini.sample**: Allowed MIME types, e.g. `image/jpeg|image/png`, use `*/*` for all types.
- `ALLOWED_TYPES`: **see app.ini.sample**: Allowed MIME types, e.g. `image/jpeg|image/png`.
Use `*/*` for all types.
- `MAX_SIZE`: **4**: Maximum size (MB).
- `MAX_FILES`: **5**: Maximum number of attachments that can be uploaded at once.
@ -231,10 +271,9 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
- `MAX_GIT_DIFF_FILES`: **100**: Max number of files shown in diff view.
- `GC_ARGS`: **\<empty\>**: Arguments for command `git gc`, e.g. `--aggressive --auto`.
## markup (`markup`)
## Markup (`markup`)
Gitea supports external markup support, you can integrate all your favorite tool. For example,
below will add a markup named `asciidoc` which is followed `markup.` ini section. And there are some config items below.
Gitea can support Markup using external tools. The example below will add a markup named `asciidoc`.
```ini
[markup.asciidoc]
@ -244,10 +283,11 @@ RENDER_COMMAND = "asciidoc --out-file=- -"
IS_INPUT_FILE = false
```
- ENABLED: Whether enable this tool. default is false.
- FILE_EXTENSIONS: List of file extensions that should be rendered by an external command. Multiple extentions needs a comma as splitter.
- RENDER_COMMAND: External command to render all matching extensions.
- IS_INPUT_FILE: Input is not a standard input but a file param followed `RENDER_COMMAND`, default is false.
- ENABLED: **false** Enable markup support.
- FILE\_EXTENSIONS: **\<empty\>** List of file extensions that should be rendered by an external
command. Multiple extentions needs a comma as splitter.
- RENDER\_COMMAND: External command to render all matching extensions.
- IS\_INPUT\_FILE: **false** Input is not a standard input but a file param followed `RENDER_COMMAND`.
## Other (`other`)

View File

@ -15,42 +15,57 @@ menu:
# Customizing Gitea
The main way to customize Gitea is by using the `custom` folder. This is the central place to override and configure features.
Customizing Gitea is typically done using the `custom` folder. This is the central
place to override configuration settings, templates, etc.
If you install Gitea from binary, after the installation process ends, you can find the `custom` folder next to the binary.
Gitea will create the folder for you and prepopulate it with a `conf` folder inside, where Gitea stores all the configuration settings provided through the installation steps (have a look [here](https://docs.gitea.io/en-us/config-cheat-sheet/) for a complete list).
If Gitea is deployed from binary, all default paths will be relative to the gitea
binary. If installed from a distribution, these paths will likely be modified to
the Linux Filesystem Standard. Gitea will create required folders, including `custom/`.
Application settings are configured in `custom/conf/app.ini`. Distributions may
provide a symlink for `custom` using `/etc/gitea/`.
If you can't find the `custom` folder next to the binary, please check the `GITEA_CUSTOM` environment variable, that can be used to override the default path to something else. `GITEA_CUSTOM` might be set for example in your launch script file. Please have a look [here](https://docs.gitea.io/en-us/specific-variables/) for a complete list of environment variables.
- [Quick Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/)
- [Complete List](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample)
**Note** that you have to restart Gitea for it to notice the changes.
If the `custom` folder can't be found next to the binary, check the `GITEA_CUSTOM`
environment variable; this can be used to override the default path to something else.
`GITEA_CUSTOM` might, for example, be set by an init script.
- [List of Environment Variables](https://docs.gitea.io/en-us/specific-variables/)
**Note:** Gitea must perform a full restart to see configuration changes.
## Customizing /robots.txt
To make Gitea serve your own `/robots.txt` (by default, an empty 404 status is served), simply create a file called `robots.txt` in the `custom` folder with the [expected contents](http://www.robotstxt.org/).
To make Gitea serve a custom `/robots.txt` (default: empty 404), create a file called
`robots.txt` in the `custom` folder with [expected contents](http://www.robotstxt.org/).
## Serving custom public files
To make Gitea serve custom public files (like pages and images), use the folder `custom/public/` as the webroot. Symbolic links will be followed.
To make Gitea serve custom public files (like pages and images), use the folder
`custom/public/` as the webroot. Symbolic links will be followed.
For example, a file `image.png` stored in `custom/public`, can be accessed with the url `http://your-gitea-url/image.png`.
For example, a file `image.png` stored in `custom/public/`, can be accessed with
the url `http://gitea.domain.tld/image.png`.
## Changing the default avatar
Place the png image at the following path: `custom/public/img/avatar_default.png`
Place the png image at the following path: `custom/public/img/avatar\_default.png`
## Customizing Gitea pages
The `custom/templates` folder allows you to change every single page of Gitea.
The `custom/templates` folder allows changing every single page of Gitea. Templates
to override can be found in the `templates` directory of Gitea source. Override by
making a copy of the file under `custom/templates` using a full path structure
matching source.
You need to be aware of the template you want to change. All templates can be found in the `templates` folder of the Gitea sources.
Any statement contained inside `{{` and `}}` are Gitea's templete syntax and
shouldn't be touched without fully understanding these components.
When you find the correct .tmpl file, you need to copy it in the `custom/templates` folder of your installation, __respecting__ any subfolder you found in the source template.
You can now customize the template you copied in `custom/templates`, being carefully to not break the Gitea syntax.
Any statement contained inside `{{` and `}}` are Gitea templete's syntax and shouldn't be touch, unless you know what are you doing.
To add in custom HTML to the header or the footer of the page, in the `templates/custom` directory there are `header.tmpl` and `footer.tmpl` that can be modified. This is useful if you want to add in custom CSS files, or additional Javascript.
To add custom HTML to the header or the footer of the page, in the `templates/custom`
directory there is `header.tmpl` and `footer.tmpl` that can be modified. This can be
a useful place to add custom CSS files or additional Javascript.
## Customizing gitignores, labels, licenses, locales, and readmes.
Place your own files in corresponding sub-folder under `custom/options`.
Place custom files in corresponding sub-folder under `custom/options`.

View File

@ -15,21 +15,28 @@ menu:
# Hacking on Gitea
We won't cover the basics of a Golang setup within this guide. If you don't know how to get the environment up and running you should follow the official [install instructions](https://golang.org/doc/install).
Familiarity with the existing [installation instructions](https://golang.org/doc/install)
is required for this section.
If you want to contribute to Gitea you should fork the project and work on the `master` branch. There is a catch though, some internal packages are referenced by their GitHub URL. So you have to trick the Go tool to think that you work on a clone of the official repository. Start by downloading the source code as you normally would:
To contribute to Gitea, fork the project and work on the `master` branch.
Some internal packages are referenced using their respective Github URL. This can
become problematic. To "trick" the Go tool into thinking this is a clone from the
official repository, download the source code using "go get" and follow these instructions.
```
go get -d code.gitea.io/gitea
```
Now it's time to fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub, after that you should have to switch to the source directory on the command line:
Fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub, it should
then be possible to switch the source directory on the command line.
```
cd $GOPATH/src/code.gitea.io/gitea
```
To be able to create pull requests you should add your forked repository as a remote to the Gitea sources, otherwise you can not apply the changes to our repository because of lacking write permissions:
To be able to create pull requests, the forked repository should be added as a remote
to the Gitea sources, otherwise changes can't be pushed.
```
git remote rename origin upstream
@ -37,6 +44,12 @@ git remote add origin git@github.com:<USERNAME>/gitea.git
git fetch --all --prune
```
You've got a working development environment for Gitea now. Take a look at the `Makefile` to get an overview about the available tasks. The most common tasks should be `make test` which will start our test environment and `make build` which will build a `gitea` binary into your working directory. Writing test cases is not mandatory to contribute, but we will be happy if you do.
This should provide a working development environment for Gitea. Take a look at
the `Makefile` to get an overview about the available tasks. The most common tasks
should be `make test` which will start our test environment and `make build` which
will build a `gitea` binary into the working directory. Writing test cases is not
mandatory to contribute, but it is highly encouraged and helps developers sleep
at night.
Thats it! You are ready to hack on Gitea. Test your changes, push them to your repository and open a pull request.
That's it! You are ready to hack on Gitea. Test changes, push them to the repository,
and open a pull request.

View File

@ -15,16 +15,17 @@ menu:
# Make
Gitea makes heavy use of Make to automate tasks and have a faster development. This guide cover how to install Make.
Gitea makes heavy use of Make to automate tasks and improve development. This
guide covers how to install Make.
### On Linux
You can install with your package manager.
Install with the package manager.
On Ubuntu/Debian:
```bash
sudo apt-get install build-essential
sudo apt-get install make
```
On Fedora/RHEL/CentOS:
@ -35,10 +36,11 @@ sudo yum install make
### On Windows
If you are using Windows, you can download and use one of these distributions of Make:
One of these three distributions of Make will run on Windows:
- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`.
- [32-bits version](ftp://ftp.equation.com/make/32/make.exe)
- [64-bits version](ftp://ftp.equation.com/make/64/make.exe)
- [MinGW](http://www.mingw.org/) includes a build. The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to your `PATH`.
- [MinGW](http://www.mingw.org/) includes a build.
- The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`.
- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make`

0
docs/content/doc/advanced/make.fr-fr.md Executable file → Normal file
View File

View File

@ -25,43 +25,45 @@ GITEA_CUSTOM=/home/gitea/custom ./gitea web
## From Go language
As Gitea is written in Go, it uses some Go variables as:
As Gitea is written in Go, it uses some Go variables, such as:
* `GOOS`
* `GOARCH`
* `GOPATH`
* [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
For `GOPATH`, check [official documentation about GOPATH environment variable](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable).
For others, check [official documentation about variables used when it runs the generator](https://golang.org/cmd/go/#hdr-Generate_Go_files_by_processing_source).
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`: Gitea absolute path of work directory.
* `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable to change *custom* directory.
* `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 launch Gitea. Useful for repository URL address on Gitea interface
* `USERNAME`: if no USER found, Gitea will try `USERNAME`
* `HOME`: User home directory path (**except if** you're running on Windows, check the following `USERPROFILE` variable)
* `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 you will use to get home directory
* `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".
* `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`: Do not run as a service on Windows if set to 1
* `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.
* `ZOOKEEPER_PATH`: [Zookeeper](http://zookeeper.apache.org/) jar file path