gitea/docs/content/doc/advanced/cmd-embedded.en-us.md
Patrick Schratz af79677a44
Reformat docs (#13897)
Co-authored-by: 6543 <6543@obermui.de>
Co-authored-by: Lauris BH <lauris@nix.lv>
2020-12-09 07:47:06 +01:00

122 lines
4.4 KiB
Markdown

---
date: "2020-01-25T21:00:00-03:00"
title: "Embedded data extraction tool"
slug: "cmd-embedded"
weight: 40
toc: false
draft: false
menu:
sidebar:
parent: "advanced"
name: "Embedded data extraction tool"
weight: 40
identifier: "cmd-embedded"
---
# 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" >}})).
To obtain a copy of the embedded resources ready for editing, the `embedded` command from the CLI
can be used from the OS shell interface.
**NOTE:** The embedded data extraction tool is included in Gitea versions 1.12 and above.
## Listing resources
To list resources embedded in Gitea's executable, use the following syntax:
```sh
gitea embedded list [--include-vendored] [patterns...]
```
The `--include-vendored` flag makes the command include vendored files, which are
normally excluded; that is, files from external libraries that are required for Gitea
(e.g. [font-awesome](https://fontawesome.com/), [octicons](https://octicons.github.com/), etc).
A list of file search patterns can be provided. Gitea uses [gobwas/glob](https://github.com/gobwas/glob)
for its glob syntax. Here are some examples:
- List all template files, in any virtual directory: `**.tmpl`
- List all mail template files: `templates/mail/**.tmpl`
- List all files inside `public/img`: `public/img/**`
Don't forget to use quotes for the patterns, as spaces, `*` and other characters might have
a special meaning for your command shell.
If no pattern is provided, all files are listed.
### 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
templates/user/auth/finalize_openid.tmpl
templates/user/auth/signin_openid.tmpl
templates/user/auth/signup_openid_connect.tmpl
templates/user/auth/signup_openid_navbar.tmpl
templates/user/auth/signup_openid_register.tmpl
templates/user/settings/security_openid.tmpl
```
## Extracting resources
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...}
```
The `--config` option tells gitea the location of the `app.ini` configuration file if
it's not in its default location. This option is only used with the `--custom` flag.
The `--destination` option tells gitea the directory where the files must be extracted to.
The default is the current directory.
The `--custom` flag tells gitea to extract the files directly into the `custom` directory.
For this to work, the command needs to know the location of the `app.ini` configuration
file (`--config`) and, depending of the configuration, be ran from the directory where
gitea normally starts. See [Customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}}) for details.
The `--overwrite` flag allows any existing files in the destination directory to be overwritten.
The `--rename` flag tells gitea to rename any existing files in the destination directory
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
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.
When Gitea is upgraded to a new version (by replacing the executable), many of the
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
Extracting mail templates to a temporary directory:
```sh
$ mkdir tempdir
$ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
Extracting to tempdir:
tempdir/templates/mail/auth/activate.tmpl
tempdir/templates/mail/auth/activate_email.tmpl
tempdir/templates/mail/auth/register_notify.tmpl
tempdir/templates/mail/auth/reset_passwd.tmpl
tempdir/templates/mail/issue/assigned.tmpl
tempdir/templates/mail/issue/default.tmpl
tempdir/templates/mail/notify/collaborator.tmpl
```