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.

⚠️ NOTE: cargo gen requires a cargo alias configuration

cargo generate username-on-github/mytemplate
# is the same as 
cargo generate gh:username-on-github/mytemplate
# is the same as 
cargo generate --git

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

# for
cargo generate gl:username-on-gitlab/mytemplate
# or for
cargo generate bb:username-on-bitbucket/mytemplate
# or for 
cargo generate gh:username-on-github/mytemplate

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 --name myproject

Templates in subfolders

If the git repository contains multiple templates, the specific subfolder in the git repository may be specified like this:

cargo generate --git <relative-template-path>

⚠️ NOTE: The specified relative-template-path will be used as the actual template root, whether or not this is actually true!

⚠️ 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

⚠️ 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 $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.

git over ssh

New in version 0.7.0 is the support for both public and private and ssh git remote urls. For example:

cargo generate --git --name mywasm

leads to the same result as:

cargo generate --git --name mywasm

as well as:

cargo generate rustwasm/wasm-pack-template --name mywasm

authentication using ssh-agent

New in version 0.15.1 is the ssh-agent usage for password protected keys. It's also the default mechanism on Windows.

On Windows

ssh-agent is the default and also the only possibility to get git+ssh working. Please follow this guide to get ssh-agent configured on windows.

On *Nix and macOS

If you omit the identity file (read the next paragraph) OR a provided identity file does not exist, then the default is to use ssh-agent.

ssh identity file (private key)

However, if you use a different file, you can pass a custom ssh identity with via -i | --identity like -i ~/.ssh/id_rsa_other as argument.

⚠️ NOTE: password protected private keys are NOT supported, you have to use ssh-agent and omit the -i argument (see above).

If you permanently want to use a custom identity file, you can configure it in the cargo-generate config file like this:

# an extract of ~/.cargo/cargo-generate.toml
# note that `~/` and `$HOME/` are going to be expanded to the full path seamlessly
ssh_identity = "~/.ssh/id_rsa_other"
# that is equivalent to 
ssh_identity = "$HOME/.ssh/id_rsa_other"
# that is equivalent to 
ssh_identity = "/home/john/.ssh/id_rsa_other"

⚠️ NOTE: that the cli argument -i always overrules the ssh_identity from the config file.

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.