Embedded data extraction tool
Table of Contents
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).
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:
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, octicons, etc).
A list of file search patterns can be provided. Gitea uses 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:
$ 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:
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 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:
$ 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