bb25f85ce8
This was intended to be a small followup for https://github.com/go-gitea/gitea/pull/23712, but...here we are. 1. Our docs currently use `slug` as the entire URL, which makes refactoring tricky (see https://github.com/go-gitea/gitea/pull/23712). Instead, this PR attempts to make future refactoring easier by using slugs as an extension of the section. (Hugo terminology) - What the above boils down to is this PR attempts to use directory organization as URL management. e.g. `usage/comparison.en-us.md` -> `en-us/usage/comparison/`, `usage/packages/overview.en-us.md` -> `en-us/usage/packages/overview/` - Technically we could even remove `slug`, as Hugo defaults to using filename, however at least with this PR it means `slug` only needs to be the name for the **current file** rather than an entire URL 2. This PR adds appropriate aliases (redirects) for pages, so anything on the internet that links to our docs should hopefully not break. 3. A minor nit I've had for a while, renaming `seek-help` to `support`. It's a minor thing, but `seek-help` has a strange connotation to it. 4. The commits are split such that you can review the first which is the "actual" change, and the second is added redirects so that the first doesn't break links elsewhere. --------- Signed-off-by: jolheiser <john.olheiser@gmail.com>
124 lines
4.4 KiB
Markdown
124 lines
4.4 KiB
Markdown
---
|
|
date: "2020-01-25T21:00:00-03:00"
|
|
title: "Embedded data extraction tool"
|
|
slug: "cmd-embedded"
|
|
weight: 20
|
|
toc: false
|
|
draft: false
|
|
aliases:
|
|
- /en-us/cmd-embedded
|
|
menu:
|
|
sidebar:
|
|
parent: "administration"
|
|
name: "Embedded data extraction tool"
|
|
weight: 20
|
|
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/administration/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/administration/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
|
|
```
|