15 releases

0.6.0-alpha.2 Feb 18, 2021
0.5.3 Feb 8, 2021
0.5.1 Sep 21, 2020
0.5.0 Oct 29, 2019
0.1.1 Jul 27, 2018

#570 in Development tools

Download history 577/week @ 2020-11-04 602/week @ 2020-11-11 790/week @ 2020-11-18 728/week @ 2020-11-25 749/week @ 2020-12-02 875/week @ 2020-12-09 756/week @ 2020-12-16 744/week @ 2020-12-23 808/week @ 2020-12-30 686/week @ 2021-01-06 757/week @ 2021-01-13 777/week @ 2021-01-20 791/week @ 2021-01-27 1258/week @ 2021-02-03 1137/week @ 2021-02-10 916/week @ 2021-02-17

3,567 downloads per month
Used in 2 crates

MIT/Apache

80KB
2K SLoC

cargo-generate

cargo, make me a project

Build status crates.io dependency status

cargo-generate is a developer tool to help you get up and running quickly with a new Rust project by leveraging a pre-existing git repository as a template.

Here's an example of using cargo-generate with this template: demo.gif

Installation

Using cargo with system's OpenSSL

cargo install cargo-generate

See the openssl-sys crate readme on how to obtain the OpenSSL library for your system. Alternatively, use the vendored-openssl flag if you do not want to install OpenSSL.

Using cargo with vendored OpenSSL

cargo install cargo-generate --features vendored-openssl

Manual Install:

  1. Download the binary tarball for your platform from our releases page.

  2. Unpack the tarball and place the binary cargo-generate in ~/.cargo/bin/

Usage

Standard usage is to pass a --git flag to cargo generate or short cargo gen. This will prompt you to enter the name of your project.

cargo generate --git https://github.com/githubusername/mytemplate.git

You can also pass the name of your project to the tool using the --name or -n flag:

cargo generate --git https://github.com/githubusername/mytemplate.git --name myproject

Favorites

Favorite templates can be defined in a config file, that by default is placed at $CARGO_HOME/cargo-generate. To specify an alternative configuration file, use the --config <config-file> option.

Each favorite template is specified in its own section, e.g.:

[favorites.demo]
description = "Demo template for cargo-generate"
git = "https://github.com/ashleygwilliams/wasm-pack-template"
branch = "master"

Both branch and description are optional, and the branch may be overridden by specifying --branch <branch> on the command line.

When favorites are available, they can be generated simply by invoking:

cargo gen <favorite>

or slightly more involved:

cargo generate demo --branch master --name expanded_demo

Templates

Templates are git repositories whose files contain placeholders. The current supported placeholders are:

  • {{authors}}: this will be filled in by a function borrowed from Cargo's source code, that determines your information from Cargo's configuration.
  • {{project-name}}: this is supplied by either passing the --name flag to the command or working with the interactive CLI to supply a name.
  • {{crate_name}}: the snake_case_version of project-name
  • {{os-arch}}: contains the current operating system and architecture ex: linux-x86_64

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

Here's a list of currently available templates. If you have a great template that you'd like to feature here, please file an issue or a PR!

Include / Exclude

Templates support a cargo-generate.toml, with a "template" section that allows you to configure the files that will be processed by cargo-generate. The behavior mirrors Cargo's Include / Exclude functionality, which is documented here. If you are using placeholders in a file name, and also wish to use placeholders in the contents of that file, you should setup your globs to match on the pre-rename filename.

[template]
include = ["Cargo.toml"]
# include and exclude are exclusive, if both appear we will use include
exclude = ["*.c"]

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. If you want to contribute to cargo-generate, please read our CONTRIBUTING notes.

Dependencies

~39MB
~895K SLoC