Usage

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

⚠️ NOTE: cargo gen requires a cargo alias configuration

# full git url
cargo generate --git https://github.com/username-on-github/mytemplate.git

# shorthand for github (org/repo expands to https://github.com/org/repo.git)
# note: if a local directory with that name exists, it is used as a path instead
cargo generate --git username-on-github/mytemplate
# is the same as
cargo generate username-on-github/mytemplate

# prefixed shorthand (works with --git or as positional argument)
cargo generate gh:username-on-github/mytemplate
# is the same as
cargo generate --git gh:username-on-github/mytemplate

If you have your templates not GitHub then you can leverage the lazy abbreviation prefixes:

# for gitlab.com
cargo generate gl:username-on-gitlab/mytemplate # translates to https://gitlab.com/username-on-gitlab/mytemplate.git
# or for bitbucket.org
cargo generate bb:username-on-bitbucket/mytemplate # translates to https://bitbucket.org/username-on-bitbucket/mytemplate.git
# or for github.com
cargo generate gh:username-on-github/mytemplate # translates to https://github.com/username-on-github/mytemplate.git
# or for git.sr.ht
cargo generate sr:username-on-sourcehut/mytemplate # translates to https://git.sr.ht/~username-on-sourcehut/mytemplate (note the tilde)

Both will expand to the https urls of the repo with the suffix .git in the URL.

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

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

Templates in subfolders

If the repository or path specified for the template contains multiple templates (Any sub-folder that contains a cargo-generate.toml file), cargo-generate will ask for the specific folder to be used as the template.

Multiple sub-templates can also be configured in the cargo-generate.toml file like this:

[template]
sub_templates = ["folder1", "folder2"]

Doing so also sets the order when cargo-generate asks what to expand, while the first option will be the default.

The specific subfolder in the git repository may be specified on the command line like this:

cargo generate --git https://github.com/username-on-github/mytemplate.git <relative-template-path>

⚠️ NOTE: When using the subfolder feature, cargo-generate will search for the cargo-generate.toml file in the subfolder first, traversing back towards the template root in case it is not found.

Generating into current dir

If the user wants to generate a template straight into the current folder, without creating a subfolder for the contents and without attempting to initialize a .git repo or similar, the --init flag can be used.

cargo generate --init --git https://github.com/username-on-github/mytemplate.git

⚠️ NOTE: cargo-generate will not allow any existing files to be overwritten and will fail to generate any files should there be any conflicts.

Generating using a local template

You can generate a project using a local template via the --path flag:

git clone https://github.com/username-on-github/mytemplate.git $HOME/mytemplate # Clone any template
cargo generate --path $HOME/mytemplate # Use it locally

⚠️ NOTE: cargo-generate will not allow to use the association --path and --git flags.

Http(s) proxy

New in version 0.7.0 is automatic proxy usage. So, if http(s)_PROXY env variables are provided, they will be used for cloning a http(s) template repository.