forgejo/docs/content/doc/usage/template-repositories.en-us.md
Kyle D 8220e50b56
Substitute variables in path names of template repos too (#25294)
### Summary

Extend the template variable substitution to replace file paths. This
can be helpful for setting up log files & directories that should match
the repository name.

### PR Changes

 - Move files matching glob pattern when setting up repos from template
- For security, added ~escaping~ sanitization for cross-platform support
and to prevent directory traversal (thanks @silverwind for the
reference)
 - Added unit testing for escaping function 
- Fixed the integration tests for repo template generation by passing
the repo_template_id
- Updated the integration testfiles to add some variable substitution &
assert the outputs

I had to fix the existing repo template integration test and extend it
to add a check for variable substitutions.

Example:

![image](https://github.com/go-gitea/gitea/assets/12700993/621feb09-0ef3-460e-afa8-da74cd84fa4e)
2023-06-20 21:14:47 +00:00

3.4 KiB

date title slug weight toc draft aliases menu
2019-11-28:00:00+02:00 Template Repositories template-repositories 14 false false
/en-us/template-repositories
sidebar
parent name weight identifier
usage Template Repositories 14 template-repositories

Template Repositories

Table of Contents

{{< toc >}}

Gitea 1.11.0 and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.

To tell Gitea which files to expand, you must include a template file inside the .gitea directory of the template repository.

Gitea uses gobwas/glob for its glob syntax. It closely resembles a traditional .gitignore, however there may be slight differences.

Example .gitea/template file

All paths are relative to the base of the repository

# All .go files, anywhere in the repository
**.go

# All text files in the text directory
text/*.txt

# A specific file
a/b/c/d.json

# Batch files in both upper or lower case can be matched
**.[bB][aA][tT]

NOTE: The template file will be removed from the .gitea directory when a repository is generated from the template.

Variable Expansion

In any file matched by the above globs, certain variables will be expanded.

Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems.

All variables must be of the form $VAR or ${VAR}. To escape an expansion, use a double $$, such as $$VAR or $${VAR}

Variable Expands To Transformable
REPO_NAME The name of the generated repository
TEMPLATE_NAME The name of the template repository
REPO_DESCRIPTION The description of the generated repository
TEMPLATE_DESCRIPTION The description of the template repository
REPO_OWNER The owner of the generated repository
TEMPLATE_OWNER The owner of the template repository
REPO_LINK The URL to the generated repository
TEMPLATE_LINK The URL to the template repository
REPO_HTTPS_URL The HTTP(S) clone link for the generated repository
TEMPLATE_HTTPS_URL The HTTP(S) clone link for the template repository
REPO_SSH_URL The SSH clone link for the generated repository
TEMPLATE_SSH_URL The SSH clone link for the template repository

Transformers 🤖

Gitea 1.12.0 adds a few transformers to some of the applicable variables above.

For example, to get REPO_NAME in PASCAL-case, your template would use ${REPO_NAME_PASCAL}

Feeding go-sdk to the available transformers yields...

Transformer Effect
SNAKE go_sdk
KEBAB go-sdk
CAMEL goSdk
PASCAL GoSdk
LOWER go-sdk
UPPER GO-SDK
TITLE Go-Sdk