Templates - Cargo Generate Documentation
Description: cargo, make me a project

# Templates

## Placeholders

Templates are git repositories whose files can contain placeholders. A placeholder can be seen as a variable that is substituted by another value upon expansion of the template.

`cargo-generate` supports both builtin variables/placeholders and custom defined ones.

Additionally, all filters and tags of the liquid template language are supported. For more information, check out the Liquid Documentation on `Tags` and `Filters`.

You can use those placeholders in the file and directory names of the generated project. For example, for a project named `awesome`, the filename `{{project-name}}/{{project-name}}.rs` will be transformed to `awesome/awesome.rs` during generation. Only files that are not listed in the exclude settings will be templated.

> ⚠️ NOTE: invalid characters for a filename or directory name will be sanitized after template substitution. Invalid is e.g. `/` or `\`.

> ⚠️ Deprecated in favor of using ignore in `cargo-generate.toml`

> You can also add a `.genignore` file to your template. The files listed in the `.genignore` file will be removed from the local machine when `cargo-generate` is run on the end user's machine. The `.genignore` file is always ignored, so there is no need to list it in the `.genignore` file.

### Additional `liquid` filters

Following are filters that `cargo-generate` expands the `liquid` language with.

- `rhai`

  Tries to run the argument as a `rhai` script. Whatever the script returns will be the output of the filter.

  Example Liquid:

      Here we try to run a rhai script: {{"script_name.rhai" | rhai}}

  > ⚠️ NOTE: `Liquid` does not support failing filters, thus if the script fails for any reason, `cargo-generate` will simply print a warning message to stderr, and `Liquid` will leave the substitution in its original form.

- `kebab_case`

  `"We are going to inherit the earth."` => `"we-are-going-to-inherit-the-earth"`

- `lower_camel_case`

  `"It is we who built these palaces and cities."` => `"itIsWeWhoBuiltThesePalacesAndCities"`

- `pascal_case`

  Same as `upper_camel_case`

- `shouty_kebab_case`

  `"We are going to inherit the earth."` => `"WE-ARE-GOING-TO-INHERIT-THE-EARTH"`

- `shouty_snake_case`

  `"That world is growing in this minute."` => `"THAT_WORLD_IS_GROWING_IN_THIS_MINUTE"`

- `snake_case`

  `"We carry a new world here, in our hearts."` => `"we_carry_a_new_world_here_in_our_hearts"`

- `title_case`

  `"We have always lived in slums and holes in the wall."` => `"We Have Always Lived In Slums And Holes In The Wall"`

- `upper_camel_case`

  `"We are not in the least afraid of ruins."` => `"WeAreNotInTheLeastAfraidOfRuins"`

## Templates by the community

It's encouraged to classify your template repository with a GitHub topic labeled `cargo-generate`.

So that every developer can find the template via cargo-generate topic on GitHub.

If you have a great template, please tag your repository with the topic and tweet about it by including the hashtag `#cargogenerate` (since twitter does not support hashtags with `-`).

> ⚠️ Note: the list of currently available templates is still available, but is now deprecated.

### Example for `--bin` and `--lib`

A template could be prepared in a way to act as a binary or a library. For example the `Cargo.toml` might look like:

    [package]
    # the usual stuff

    [dependencies]
    {% if crate_type == "bin" %}
    structopt = "0.3.21"
    {% endif %}
    # other general dependencies

    {% if crate_type == "bin" %}
    [[bin]]
    path = "src/main.rs"
    name = "{{crate_name}}-cli"
    {% endif %}

Now a user of this template could decide weather they want the binary version by passing `--bin` or use only the library version by passing `--lib` as a command line argument.