2019-11-30 07:54:47 +01:00
---
date: "2019-11-28:00:00+02:00"
2020-01-28 14:57:15 +01:00
title: "Template Repositories"
slug: "template-repositories"
2023-07-26 06:53:13 +02:00
sidebar_position: 14
2020-12-09 07:47:06 +01:00
toc: false
2019-11-30 07:54:47 +01:00
draft: false
Refactor docs (#23752)
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>
2023-04-28 05:33:41 +02:00
aliases:
- /en-us/template-repositories
2019-11-30 07:54:47 +01:00
menu:
sidebar:
2020-01-28 14:57:15 +01:00
parent: "usage"
name: "Template Repositories"
2023-07-26 06:53:13 +02:00
sidebar_position: 14
2020-01-28 14:57:15 +01:00
identifier: "template-repositories"
2019-11-30 07:54:47 +01:00
---
2020-12-09 07:47:06 +01:00
# Template Repositories
2023-10-06 08:51:33 +02:00
Gitea (starting with version `1.11.0` ) supports creating template repositories
which can be used to generate repositories based on the template, complete with
variable expansion of certain pre-defined variables.
2022-07-28 03:22:47 +02:00
2023-10-06 08:51:33 +02:00
All files in the template repository are included in a generated repository from the
template except for the `.gitea/template` file. The `.gitea/template` file tells
Gitea which files are subject to the variable expansion when creating a
repository from the template.
2022-07-28 03:22:47 +02:00
2019-11-30 07:54:47 +01:00
Gitea uses [gobwas/glob ](https://github.com/gobwas/glob ) for its glob syntax. It closely resembles a traditional `.gitignore` , however there may be slight differences.
2020-12-09 07:47:06 +01:00
## Example `.gitea/template` file
2019-11-30 07:54:47 +01:00
All paths are relative to the base of the repository
2020-12-09 07:47:06 +01:00
2019-11-30 07:54:47 +01:00
```gitignore
2023-10-06 08:51:33 +02:00
# Expand all .go files, anywhere in the repository
2019-11-30 07:54:47 +01:00
**.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]
```
2020-12-09 07:47:06 +01:00
## Variable Expansion
2022-07-28 03:22:47 +02:00
In any file matched by the above globs, certain variables will be expanded.
2023-06-20 23:14:47 +02:00
Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems.
2019-11-30 07:54:47 +01:00
All variables must be of the form `$VAR` or `${VAR}` . To escape an expansion, use a double `$$` , such as `$$VAR` or `$${VAR}`
2020-01-28 14:57:15 +01:00
| Variable | Expands To | Transformable |
2020-12-09 07:47:06 +01:00
| -------------------- | --------------------------------------------------- | ------------- |
2020-01-28 14:57:15 +01:00
| 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 | ✘ |
2020-12-09 07:47:06 +01:00
## Transformers :robot:
2022-07-28 03:22:47 +02:00
Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
2020-01-28 14:57:15 +01:00
For example, to get `REPO_NAME` in `PASCAL` -case, your template would use `${REPO_NAME_PASCAL}`
Feeding `go-sdk` to the available transformers yields...
2020-12-09 07:47:06 +01:00
| Transformer | Effect |
| ----------- | ------ |
| SNAKE | go_sdk |
| KEBAB | go-sdk |
| CAMEL | goSdk |
| PASCAL | GoSdk |
| LOWER | go-sdk |
| UPPER | GO-SDK |
| TITLE | Go-Sdk |