A GitHub CLI extension to format a project template.
Make sure you have version 2.0 or newer of the GitHub CLI installed.
gh extension install heaths/gh-template
To create a new repository from a template and format it:
gh template clone <name> --template <template> --public
You can format files in a template repository as template files.
Template files contain a mix of text and actions surrounded by {{
and }}
e.g.,
# {{param "name" "" "What is the project name?" | titlecase}}
This is an example repository {{param "github.owner"}}/{{param "github.repo"}}.
You'll be prompted for any parameters not specified on the command line
or already defined by the apply
command.
Directories and files are processed alphabetically, so you only need to provide a default value and optional prompt for the first instance a parameter occurs alphabetically in the repository.
Because the .github/workflows directory may contain workflows with ${{ }}
expressions,
it is excluded automatically unless --delims
is specified and not {{
or }}
.
If you need to format workflows as a template, consider using alternate delimiters
throughout your template repository e.g, <%
and %>
.
Within a GitHub repository, the following parameters are already defined.
git.name
user.name
for a Git repository.git.email
user.email
for a Git repository.github.host
github.owner
github.repo
In addition to built-in functions, the following functions are also available:
param <name> [<default> [<prompt>]]
<name>
, or prompt using an optional <default>
<prompt>
. If a <prompt>
is not specified, the required<name>
is used. The type of <default>
dictates valid input. Only string
int
are supported at this time.pluralize <count> <thing>
<thing>
if <count>
is not equal to 1. <count>
can beint
or a string
representing an int
e.g., "1".lowercase <string>
<string>
to all lowercase characters.titlecase <string>
<string>
to Title Case characters.uppercase <string>
<string>
to UPPERCASE characters.replace <from> <to> <source>
<from>
to <to>
in the <source>
string.date
date.Format <layout>
time.Format
.date.Local
date
functionsdate.Local.Year
.date.Year
true
true
. Useful as a default value to accept y[es] or n[o] answers.false
false
. Useful as a default value to accept y[es] or n[o] answers.deleteFile
You can also nest function calls. To default a project name to the GitHub repo name, for example:
{{param "name" (param "github.repo") "What is the project name?"}}
See the following template repositories for examples:
Licensed under the MIT license.