https://github.com/heaths/gh-template

GitHub CLI extension to clone and format a template repository. Create new repos from templates to get up and running quickly e.g., `gh template clone my-crate --template heaths/template-rustlang`.
https://github.com/heaths/gh-template

gh-extension template template-repository

Last synced: 3 months ago
JSON representation

GitHub CLI extension to clone and format a template repository. Create new repos from templates to get up and running quickly e.g., `gh template clone my-crate --template heaths/template-rustlang`.

• Host: GitHub
• URL: https://github.com/heaths/gh-template
• Owner: heaths
• License: mit
• Created: 2022-11-20T05:28:57.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2024-02-29T07:17:36.000Z (11 months ago)
• Last Synced: 2024-11-01T14:37:00.603Z (3 months ago)
• Topics: gh-extension, template, template-repository
• Language: Go
• Homepage:
• Size: 187 KB
• Stars: 13
• Watchers: 2
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

        
# Project Template Extension

[![releases](https://img.shields.io/github/v/release/heaths/gh-template?logo=github)](https://github.com/heaths/gh-template/releases/latest)

[![ci](https://github.com/heaths/gh-template/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/heaths/gh-template/actions/workflows/ci.yml)

A [GitHub CLI] extension to format a project template.

## Install

Make sure you have version 2.0 or [newer] of the [GitHub CLI] installed.

```bash

gh extension install heaths/gh-template

```

## Usage

To create a new repository from a template and format it:

```bash

gh template clone  --template  --public

```

![screenshot](assets/gh-template.gif)

## Templates

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.,

```markdown

# {{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 `%>`.

### Built-in parameters

Within a GitHub repository, the following parameters are already defined.

* `git.name`\

  The configured `user.name` for a Git repository.

* `git.email`\

  The configured `user.email` for a Git repository.

* `github.host`\

  The GitHub host e.g., "github.com" for "github.com/heaths/gh-template".

* `github.owner`\

  The GitHub owner e.g., "heaths" for "github.com/heaths/gh-template".

* `github.repo`\

  The GitHub repository name e.g., "gh-template" for "github.com/heaths/gh-template".

### Functions

In addition to [built-in](https://pkg.go.dev/text/template#hdr-Functions) functions,

the following functions are also available:

* `param  [ []]`\

  Replace with a parameter named ``, or prompt using an optional ``

  with an optional ``. If a `` is not specified, the required

  `` is used. The type of `` dictates valid input. Only `string`

  and `int` are supported at this time.

* `pluralize  `\

  Append an "s" to `` if `` is not equal to 1. `` can be

  either an `int` or a `string` representing an `int` e.g., "1".

* `lowercase `\

  Change the case of `` to all lowercase characters.

* `titlecase `\

  Change the case of `` to Title Case characters.

* `uppercase `\

  Change the case of `` to UPPERCASE characters.

* `replace   `\

  Replaces all occurrences of `` to `` in the `` string.

* `date`\

  Returns the current UTC date-time.

* `date.Format `\

  Formats the date-time according to [`time.Format`](https://pkg.go.dev/time#Time.Format).

* `date.Local`\

  Returns the current local date-time. You can call other `date` functions

  on the returned value e.g., `date.Local.Year`.

* `date.Year`\

  Returns the current UTC year.

* `true`\

  Returns `true`. Useful as a default value to accept y\[es\] or n\[o\] answers.

* `false`\

  Returns `false`. Useful as a default value to accept y\[es\] or n\[o\] answers.

* `deleteFile`\

  Deletes the current file, or a list of file names relative to the repo root.

You can also nest function calls. To default a project name to the GitHub repo name, for example:

```text

{{param "name" (param "github.repo") "What is the project name?"}}

```

### Examples

See the following template repositories for examples:

* [heaths/template-golang](https://github.com/heaths/template-golang)

* [heaths/template-rustlang](https://github.com/heaths/template-rustlang)

## License

Licensed under the [MIT](LICENSE.txt) license.

[GitHub CLI]: https://github.com/cli/cli

[newer]: https://github.com/cli/cli/releases/latest