= cargo template
:toc:

A utility for creating cargo projects from existing projects or templates

== Usage

The easiest way to install is through `cargo install`:

[source,bash]
----
$ cargo install cargo-template
----

After this you can create new `rust` projects this way:

[source,bash]
----
$ cargo template ~/path/to/my/template my-new-project
----

You can also use our template index if you don't have any templates locally:

[source,bash]
----
$ cargo template iron-basic my-new-iron-project
----

This requires an internet connection, and will put templates in `~/.cargo/cargo-template`.

The index and templates get saved to your `~/.cargo` directory, so if you know the template you want
is in there, you can pass `--frozen` to `cargo-template` to ensure that it won't try to use the network.

One issue with using `cargo install` to install `cargo-template` is that we use `cargo` so that we can
handle cargo config files in a consistent way. Unfortunately most of `cargo` is one big library, so
we can't just pull in the `cargo/config` parts of it, we have to pull in & compile all of it. Since
`cargo install` builds in `--release` mode, that means it takes a _while_ to compile `cargo`. Hopefully
one day `cargo` will be split up into smaller crates where possible.

== Configuration

By default, `cargo-template` will use our index, `https://github.com/rusttemplates/templates.git`. But
this can be changed by editing your `~/.cargo/config` file.

[source,toml]
----
[template.registry]
index = "https://github.com/foo/bar"
----

== Caveats

Right now this is the absolute bare minimum I needed for this to work, so there are quite a few things missing, and there
is bound to be bugs. PRs welcome!

== Contributing Templates

If you would like to contribute to template back to us, well, thanks! Here is how you can do that:

  1. Fork & checkout the template registry, `https://github.com/rusttemplates/templates`
  2. Open the `index.json` file, and in the `index` array, add an object that contains
     the `name` and `loc` (location) of your template.
  3. Open a Pull Request back to the index
  4. Bask in your awesomeness!